Improve plan readiness semantics and npm release resilience

.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();

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

@@ -6,6 +6,7 @@ import { emitRuntimeFeedback, type RuntimeFeedbackSink } from "../types/runtime-
 import type { ResourceState } from "../types/state.ts";
 import { contentHash } from "../utils/hash.ts";
 import { getResourceDeclaration } from "./declaration.ts";
+import { diffChangedPaths } from "./plan-semantics.ts";
 
 export interface RefreshResult {
 	removed: ResourceState[];
@@ -75,6 +76,10 @@ export async function refreshState(
 				const desiredComparableHash = desiredComparable === null ? undefined : contentHash(desiredComparable);
 				const baselineHash = res.desired_comparable_hash ?? desiredComparableHash;
 				const driftStatus = baselineHash && remoteHash !== baselineHash ? "drifted" : "in_sync";
+				const driftPaths =
+					driftStatus === "drifted" && desiredComparable !== null
+						? diffChangedPaths(desiredComparable, remote.comparable)
+						: [];
 
 				state.setResource({
 					...res,
@@ -84,6 +89,7 @@ export async function refreshState(
 					desired_comparable_hash: res.desired_comparable_hash ?? desiredComparableHash,
 					remote_hash: remoteHash,
 					remote_snapshot: remote.snapshot ?? remote.comparable,
+					drift_paths: driftPaths,
 					drift_status: driftStatus,
 				});
 				dirty = true;

packages/sdk/src/internal/state/state-manager.ts

@@ -43,8 +43,10 @@ export class StateManager implements IStateManager {
 				content_hash: ((r.content_hash ?? r.desired_hash) as string) ?? "",
 				desired_hash: ((r.desired_hash ?? r.content_hash) as string) ?? "",
 				desired_comparable_hash: r.desired_comparable_hash as string | undefined,
+				desired_readiness_baseline: r.desired_readiness_baseline as ResourceState["desired_readiness_baseline"],
 				remote_hash: r.remote_hash as string | undefined,
 				remote_snapshot: r.remote_snapshot,
+				drift_paths: r.drift_paths as string[] | undefined,
 				drift_status: r.drift_status as ResourceState["drift_status"],
 			}));
 			return new StateManager({ resources }, path);

packages/sdk/src/internal/types/dto.ts

@@ -35,11 +35,16 @@ export type ActionType = z.infer<typeof ActionTypeSchema>;
 export const DriftKindSchema = z.enum(["none", "local", "remote", "both"]);
 export type DriftKind = z.infer<typeof DriftKindSchema>;
 
+export const PlanReadinessImpactSchema = z.enum(["none", "non_blocking", "blocking"]);
+export type PlanReadinessImpact = z.infer<typeof PlanReadinessImpactSchema>;
+
 export const PlannedActionSchema = z.object({
 	action: ActionTypeSchema,
 	address: ResourceAddressSchema,
 	reason: z.string(),
 	driftKind: DriftKindSchema.optional(),
+	readinessImpact: PlanReadinessImpactSchema.optional(),
+	changedPaths: z.array(z.string()).optional(),
 	before: z.record(z.string(), z.unknown()).optional(),
 	after: z.record(z.string(), z.unknown()).optional(),
 	dependencies: z.array(ResourceAddressSchema),

packages/sdk/src/internal/types/state.ts

@@ -13,11 +13,19 @@ export interface ResourceState {
 	content_hash: string;
 	desired_hash?: string;
 	desired_comparable_hash?: string;
+	desired_readiness_baseline?: ResourceReadinessBaseline;
 	remote_hash?: string;
 	remote_snapshot?: unknown;
+	drift_paths?: string[];
 	drift_status?: "in_sync" | "drifted" | "missing" | "unchecked";
 }
 
+export interface ResourceReadinessBaseline {
+	operational_hash: string;
+	description_hash: string;
+	metadata_hash: string;
+}
+
 export interface StateFile {
 	resources: ResourceState[];
 }