Improve plan readiness semantics and npm release resilience (#20)

* fix: tolerate npm registry propagation delays [policy]

Change-Id: I2fda5eedb254b1b2caa0a624b45a96d496db530d

* feat: classify plan readiness impact

Change-Id: I329bd0b0f21f7ded2bf21671cdead6a264aab0f0

Author: heimanba

.changeset/structured-plan-semantics.md

@@ -0,0 +1,5 @@
+---
+"@openagentpack/sdk": patch
+---
+
+Classify Agent readiness from structured plan impact and changed paths instead of parsing display text.

.github/workflows/release.yml

@@ -121,6 +121,7 @@ jobs:
   registry-ready:
     needs: [preflight, publish]
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     permissions:
       contents: read
     steps:

apps/server/openapi.json

@@ -803,6 +803,16 @@
 																			"type": "string",
 																			"enum": ["none", "local", "remote", "both"]
 																		},
+																		"readinessImpact": {
+																			"type": "string",
+																			"enum": ["none", "non_blocking", "blocking"]
+																		},
+																		"changedPaths": {
+																			"type": "array",
+																			"items": {
+																				"type": "string"
+																			}
+																		},
 																		"before": {
 																			"type": "object",
 																			"additionalProperties": {

apps/webui/src/lib/api/generated/schema.d.ts

@@ -298,6 +298,9 @@ export interface paths {
 										reason: string;
 										/** @enum {string} */
 										driftKind?: "none" | "local" | "remote" | "both";
+										/** @enum {string} */
+										readinessImpact?: "none" | "non_blocking" | "blocking";
+										changedPaths?: string[];
 										before?: {
 											[key: string]: unknown;
 										};

packages/sdk/src/index.ts

@@ -192,6 +192,7 @@ export {
 	ListSessionsRequestSchema,
 	ListSessionsResponseSchema,
 	PlannedActionSchema,
+	PlanReadinessImpactSchema,
 	ResourceAddressSchema,
 	ResourceTypeSchema,
 	SendEventRequestSchema,
@@ -232,6 +233,7 @@ export type {
 	ListSessionsRequest,
 	ListSessionsResponse,
 	PlannedAction,
+	PlanReadinessImpact,
 	ResourceAddress,
 	ResourceType,
 	SendEventRequest,

packages/sdk/src/internal/core/agent-runtime.ts

@@ -474,9 +474,7 @@ function actionKey(action: PlannedAction): string {
 
 function isNonBlockingAgentDrift(action: PlannedAction): boolean {
 	if (action.action === "no-op") return true;
-	if (action.action !== "update") return false;
-	const reason = action.reason.toLowerCase();
-	return reason.includes("metadata") || reason.includes("description");
+	return action.readinessImpact === "non_blocking";
 }
 
 export function collectAgentAddresses(config: ProjectConfig, agentName: string, provider?: string): ResourceAddress[] {

packages/sdk/src/internal/core/resource-runtime.ts

@@ -1,5 +1,7 @@
 import { UserError } from "../errors.ts";
 import { type ExecutionResult, executePlan } from "../executor/executor.ts";
+import { getResourceDeclaration } from "../planner/declaration.ts";
+import { buildReadinessBaseline } from "../planner/plan-semantics.ts";
 import { buildPlan } from "../planner/planner.ts";
 import { type RefreshResult, refreshState } from "../planner/refresh.ts";
 import type { ExecutionPlan, PlannedAction } from "../types/plan.ts";
@@ -126,6 +128,7 @@ export async function importResource(
 		version: options.resourceVersion,
 		content_hash: contentHash,
 		desired_hash: contentHash,
+		desired_readiness_baseline: buildReadinessBaseline(getResourceDeclaration(address, ctx.config)),
 	};
 	ctx.state.setResource(resource);
 	await ctx.state.save();

packages/sdk/src/internal/executor/executor.ts

@@ -1,7 +1,9 @@
 import { dirname, resolve } from "node:path";
 import { UserError } from "../errors.ts";
 import { computeComparableDesiredHash } from "../planner/comparable.ts";
+import { getResourceDeclaration } from "../planner/declaration.ts";
 import { computeResourceHash } from "../planner/hasher.ts";
+import { buildReadinessBaseline } from "../planner/plan-semantics.ts";
 import { ApiError, ConflictError } from "../providers/base-client.ts";
 import { readComparableIfSupported } from "../providers/drift-support.ts";
 import type { RemoteResource } from "../providers/interface.ts";
@@ -454,8 +456,10 @@ async function executeAction(action: PlannedAction, provider: ResourceExecAdapte
 		content_hash: hash,
 		desired_hash: hash,
 		desired_comparable_hash: remoteHash,
+		desired_readiness_baseline: buildReadinessBaseline(getResourceDeclaration(address, ctx.config)),
 		remote_hash: remoteHash,
 		remote_snapshot: remoteSnapshot,
+		drift_paths: [],
 		drift_status: remoteHash ? "in_sync" : undefined,
 	});
 	return adopted;

packages/sdk/src/internal/planner/plan-semantics.ts

@@ -0,0 +1,72 @@
+import type { ActionType, PlanReadinessImpact } from "../types/dto.ts";
+import type { ResourceReadinessBaseline } from "../types/state.ts";
+import { contentHash } from "../utils/hash.ts";
+
+const NON_BLOCKING_ROOT_FIELDS = new Set(["description", "metadata"]);
+
+/**
+ * Return stable, leaf-oriented paths whose values differ between two JSON-like
+ * resource snapshots. Arrays are treated atomically because their ordering is
+ * part of the declared resource semantics.
+ */
+export function diffChangedPaths(before: unknown, after: unknown, prefix = ""): string[] {
+	if (Object.is(before, after)) return [];
+	if (Array.isArray(before) || Array.isArray(after)) {
+		return structurallyEqual(before, after) ? [] : [prefix || "$root"];
+	}
+	if (isRecord(before) && isRecord(after)) {
+		const paths: string[] = [];
+		const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+		for (const key of [...keys].sort()) {
+			const path = prefix ? `${prefix}.${key}` : key;
+			paths.push(...diffChangedPaths(before[key], after[key], path));
+		}
+		return paths;
+	}
+	return [prefix || "$root"];
+}
+
+/**
+ * Classify whether an already-provisioned Agent Harness can keep running while
+ * a planned action is pending. Unknown changes are deliberately blocking.
+ */
+export function classifyReadinessImpact(
+	action: ActionType,
+	changedPaths: readonly string[] | undefined,
+): PlanReadinessImpact {
+	if (action === "no-op") return "none";
+	if (action !== "update" || !changedPaths || changedPaths.length === 0) return "blocking";
+	return changedPaths.every(isNonBlockingPath) ? "non_blocking" : "blocking";
+}
+
+/** Store only irreversible hashes in state; declarations may contain secrets. */
+export function buildReadinessBaseline(declaration: unknown): ResourceReadinessBaseline {
+	const record = isRecord(declaration) ? declaration : {};
+	const { description: _description, metadata: _metadata, ...operational } = record;
+	return {
+		operational_hash: contentHash(operational),
+		description_hash: contentHash(record.description ?? null),
+		metadata_hash: contentHash(record.metadata ?? null),
+	};
+}
+
+export function diffReadinessBaseline(before: ResourceReadinessBaseline, after: ResourceReadinessBaseline): string[] {
+	const paths: string[] = [];
+	if (before.operational_hash !== after.operational_hash) paths.push("$operational");
+	if (before.description_hash !== after.description_hash) paths.push("description");
+	if (before.metadata_hash !== after.metadata_hash) paths.push("metadata");
+	return paths;
+}
+
+function isNonBlockingPath(path: string): boolean {
+	const root = path.split(".", 1)[0];
+	return root !== undefined && NON_BLOCKING_ROOT_FIELDS.has(root);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function structurallyEqual(left: unknown, right: unknown): boolean {
+	return contentHash(left) === contentHash(right);
+}

packages/sdk/src/internal/planner/planner.ts

@@ -9,7 +9,9 @@ import type { ProjectConfig } from "../types/config.ts";
 import type { ExecutionPlan, PlannedAction } from "../types/plan.ts";
 import type { ResourceAddress, StateFile } from "../types/state.ts";
 import { addressKey } from "../types/state.ts";
+import { getResourceDeclaration } from "./declaration.ts";
 import { computeResourceHash } from "./hasher.ts";
+import { buildReadinessBaseline, classifyReadinessImpact, diffReadinessBaseline } from "./plan-semantics.ts";
 
 export interface PlanOptions {
 	providers?: string[];
@@ -48,6 +50,7 @@ export async function buildPlan(
 				action: "create",
 				address,
 				driftKind: "none",
+				readinessImpact: "blocking",
 				reason: "Resource does not exist in state",
 				after: { content_hash: desiredHash },
 				dependencies: deps,
@@ -56,10 +59,13 @@ export async function buildPlan(
 			(existing.desired_hash ?? existing.content_hash) !== desiredHash &&
 			existing.drift_status === "drifted"
 		) {
+			const changedPaths = collectChangedPaths(address, config, existing, true);
 			actions.push({
 				action: "update",
 				address,
 				driftKind: "both",
+				readinessImpact: classifyReadinessImpact("update", changedPaths),
+				changedPaths,
 				reason: "Local config changed and remote drift detected",
 				before: {
 					content_hash: existing.desired_hash ?? existing.content_hash,
@@ -70,20 +76,26 @@ export async function buildPlan(
 				dependencies: deps,
 			});
 		} else if ((existing.desired_hash ?? existing.content_hash) !== desiredHash) {
+			const changedPaths = collectChangedPaths(address, config, existing, false);
 			actions.push({
 				action: "update",
 				address,
 				driftKind: "local",
+				readinessImpact: classifyReadinessImpact("update", changedPaths),
+				changedPaths,
 				reason: "Local config changed",
 				before: { content_hash: existing.desired_hash ?? existing.content_hash },
 				after: { content_hash: desiredHash },
 				dependencies: deps,
 			});
 		} else if (existing.drift_status === "drifted") {
+			const changedPaths = existing.drift_paths;
 			actions.push({
 				action: "update",
 				address,
 				driftKind: "remote",
+				readinessImpact: classifyReadinessImpact("update", changedPaths),
+				changedPaths,
 				reason: "Remote drift detected",
 				before: {
 					content_hash: existing.desired_hash ?? existing.content_hash,
@@ -98,6 +110,7 @@ export async function buildPlan(
 				action: "no-op",
 				address,
 				driftKind: "none",
+				readinessImpact: "none",
 				reason:
 					existing.drift_status === "unchecked"
 						? "No changes detected (remote content drift unchecked)"
@@ -116,6 +129,7 @@ export async function buildPlan(
 			action: "delete",
 			address: res.address,
 			driftKind: "none",
+			readinessImpact: "blocking",
 			reason: "Resource removed from configuration",
 			before: { content_hash: res.desired_hash ?? res.content_hash },
 			dependencies: [],
@@ -125,6 +139,21 @@ export async function buildPlan(
 	return { actions, diagnostics: diagnostics.getAll() };
 }
 
+function collectChangedPaths(
+	address: ResourceAddress,
+	config: ProjectConfig,
+	existing: StateFile["resources"][number],
+	includeRemote: boolean,
+): string[] | undefined {
+	const current = buildReadinessBaseline(getResourceDeclaration(address, config));
+	const localPaths = existing.desired_readiness_baseline
+		? diffReadinessBaseline(existing.desired_readiness_baseline, current)
+		: undefined;
+	if (!includeRemote) return localPaths;
+	if (!localPaths && !existing.drift_paths) return undefined;
+	return [...new Set([...(localPaths ?? []), ...(existing.drift_paths ?? [])])].sort();
+}
+
 function getDependencies(address: ResourceAddress, graph: ReturnType<typeof buildDependencyGraph>): ResourceAddress[] {
 	const key = addressKey(address);
 	const depKeys = graph.edges.get(key) ?? new Set();