@botiverse/raft-sdk 0.3.2 → 0.4.1

package/dist/esm/index.js

@@ -4477,12 +4477,6 @@ const destructive = {
 	destructive: true,
 	audience: "both"
 };
-const managedNaturalWrite = {
-	sideEffect: "write",
-	idempotency: "natural",
-	destructive: false,
-	audience: "managed"
-};
 const managedWrite = {
 	sideEffect: "write",
 	idempotency: "none",
@@ -4543,15 +4537,6 @@ const AGENT_API_ROUTE_META = {
 	taskConvert: write,
 	taskAmend: destructive,
 	taskHistory: read,
-	migrationBegin: {
-		sideEffect: "write",
-		idempotency: "none",
-		destructive: true,
-		audience: "managed"
-	},
-	migrationStatus: read,
-	migrationReady: managedNaturalWrite,
-	migrationArrived: managedNaturalWrite,
 	reminderList: read,
 	reminderCreate: managedWrite,
 	reminderCancel: naturalDestructive,
@@ -5005,7 +4990,14 @@ const agentApiHistoryQuerySchema = passthroughObject({
 	before: optionalStringSchema,
 	after: optionalStringSchema,
 	around: optionalStringSchema,
-	limit: optionalStringSchema
+	limit: optionalStringSchema,
+	/**
+	* `"false"` reads without consuming: the Server returns the page but does
+	* not advance the agent's read cursor, and reports no
+	* `model_seen_up_to_seq`. For reads whose output may never reach the model
+	* (code a hosted agent wrote). Absent or `"true"` keeps the default.
+	*/
+	consume: _enum(["true", "false"]).optional()
 });
 const agentApiKnowledgeGetQuerySchema = passthroughObject({
 	topic: string().trim().min(1),
@@ -6131,61 +6123,6 @@ const agentApiAppConfigResponseSchema = passthroughObject({
 	overrides: record(string(), agentApiAppConfigValueSchema),
 	effective: record(string(), agentApiAppConfigValueSchema)
 });
-const agentApiMigrationStateSchema = _enum([
-	"provisioning",
-	"prep",
-	"ready",
-	"in_transit",
-	"arriving",
-	"starting",
-	"cancel_requested_pre_flip",
-	"cancel_requested_post_flip",
-	"canceled_pre_flip",
-	"canceled_post_flip",
-	"completed",
-	"aborted",
-	"failed"
-]);
-const agentApiMigrationSummarySchema = passthroughObject({
-	id: string(),
-	agentId: string(),
-	sourceMachineId: string(),
-	targetMachineId: string(),
-	state: agentApiMigrationStateSchema,
-	manifestPath: nullableStringSchema,
-	manifestSha256: nullableStringSchema,
-	arrivalReportPath: nullableStringSchema,
-	arrivalReportSha256: nullableStringSchema,
-	abortReason: nullableStringSchema,
-	failureReason: nullableStringSchema,
-	prepDeadlineAt: string().datetime(),
-	transferDeadlineAt: string().datetime(),
-	arrivalDeadlineAt: string().datetime(),
-	readyAt: nullableStringSchema,
-	flippedAt: nullableStringSchema,
-	arrivedAt: nullableStringSchema,
-	completedAt: nullableStringSchema,
-	abortedAt: nullableStringSchema,
-	revision: number$1().int().positive(),
-	createdAt: string().datetime(),
-	updatedAt: string().datetime()
-});
-const agentApiMigrationBeginBodySchema = passthroughObject({
-	targetMachineId: string().trim().min(1),
-	prepDeadlineMs: number$1().int().positive().optional(),
-	transferDeadlineMs: number$1().int().positive().optional(),
-	arrivalDeadlineMs: number$1().int().positive().optional()
-});
-const agentApiMigrationReadyBodySchema = passthroughObject({
-	manifestPath: string().trim().min(1),
-	manifestSha256: optionalStringSchema
-});
-const agentApiMigrationArrivedBodySchema = passthroughObject({
-	reportPath: optionalStringSchema,
-	reportSha256: optionalStringSchema
-});
-const agentApiMigrationResponseSchema = passthroughObject({ migration: agentApiMigrationSummarySchema });
-const agentApiMigrationStatusResponseSchema = passthroughObject({ migration: agentApiMigrationSummarySchema.nullable() });
 const agentApiPushWebhookRegisterBodySchema = object({
 	/** Public HTTPS endpoint that receives `raft-agent-inbox-notice.v1` POSTs. */
 	url: string().trim().min(1),
@@ -6787,58 +6724,6 @@ const agentApiContract = {
 		request: { query: agentApiTaskHistoryQuerySchema },
 		response: { body: agentApiTaskHistoryResponseSchema }
 	}),
-	migrationBegin: route({
-		key: "migrationBegin",
-		method: "POST",
-		path: "/migrations",
-		client: {
-			resource: "migrations",
-			method: "begin"
-		},
-		capability: "server",
-		description: "Begin a migration for the bound agent credential.",
-		request: { body: agentApiMigrationBeginBodySchema },
-		response: { body: agentApiMigrationResponseSchema }
-	}),
-	migrationStatus: route({
-		key: "migrationStatus",
-		method: "GET",
-		path: "/migrations/current",
-		client: {
-			resource: "migrations",
-			method: "status"
-		},
-		capability: "read",
-		description: "Read the active migration for the bound agent credential, if any.",
-		request: {},
-		response: { body: agentApiMigrationStatusResponseSchema }
-	}),
-	migrationReady: route({
-		key: "migrationReady",
-		method: "POST",
-		path: "/migrations/ready",
-		client: {
-			resource: "migrations",
-			method: "ready"
-		},
-		capability: "read",
-		description: "Mark the bound agent's active migration prep phase ready.",
-		request: { body: agentApiMigrationReadyBodySchema },
-		response: { body: agentApiMigrationResponseSchema }
-	}),
-	migrationArrived: route({
-		key: "migrationArrived",
-		method: "POST",
-		path: "/migrations/arrived",
-		client: {
-			resource: "migrations",
-			method: "arrived"
-		},
-		capability: "read",
-		description: "Mark the bound agent's active migration arrival phase complete.",
-		request: { body: agentApiMigrationArrivedBodySchema },
-		response: { body: agentApiMigrationResponseSchema }
-	}),
 	reminderList: route({
 		key: "reminderList",
 		method: "GET",
@@ -8871,106 +8756,6 @@ const AGENT_API_ROUTE_MANIFEST = [
 			"body": true
 		}
 	},
-	{
-		"key": "migrationBegin",
-		"method": "POST",
-		"path": "/migrations",
-		"fullPath": "/internal/agent-api/migrations",
-		"client": {
-			"resource": "migrations",
-			"method": "begin"
-		},
-		"capability": "server",
-		"description": "Begin a migration for the bound agent credential.",
-		"sideEffect": "write",
-		"idempotency": "none",
-		"destructive": true,
-		"audience": "managed",
-		"request": {
-			"params": false,
-			"query": false,
-			"body": true
-		},
-		"response": {
-			"kind": "json",
-			"body": true
-		}
-	},
-	{
-		"key": "migrationStatus",
-		"method": "GET",
-		"path": "/migrations/current",
-		"fullPath": "/internal/agent-api/migrations/current",
-		"client": {
-			"resource": "migrations",
-			"method": "status"
-		},
-		"capability": "read",
-		"description": "Read the active migration for the bound agent credential, if any.",
-		"sideEffect": "read",
-		"idempotency": "natural",
-		"destructive": false,
-		"audience": "both",
-		"request": {
-			"params": false,
-			"query": false,
-			"body": false
-		},
-		"response": {
-			"kind": "json",
-			"body": true
-		}
-	},
-	{
-		"key": "migrationReady",
-		"method": "POST",
-		"path": "/migrations/ready",
-		"fullPath": "/internal/agent-api/migrations/ready",
-		"client": {
-			"resource": "migrations",
-			"method": "ready"
-		},
-		"capability": "read",
-		"description": "Mark the bound agent's active migration prep phase ready.",
-		"sideEffect": "write",
-		"idempotency": "natural",
-		"destructive": false,
-		"audience": "managed",
-		"request": {
-			"params": false,
-			"query": false,
-			"body": true
-		},
-		"response": {
-			"kind": "json",
-			"body": true
-		}
-	},
-	{
-		"key": "migrationArrived",
-		"method": "POST",
-		"path": "/migrations/arrived",
-		"fullPath": "/internal/agent-api/migrations/arrived",
-		"client": {
-			"resource": "migrations",
-			"method": "arrived"
-		},
-		"capability": "read",
-		"description": "Mark the bound agent's active migration arrival phase complete.",
-		"sideEffect": "write",
-		"idempotency": "natural",
-		"destructive": false,
-		"audience": "managed",
-		"request": {
-			"params": false,
-			"query": false,
-			"body": true
-		},
-		"response": {
-			"kind": "json",
-			"body": true
-		}
-	},
 	{
 		"key": "reminderList",
 		"method": "GET",
@@ -9873,7 +9658,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "337bf2c7ff90b908";
+const AGENT_API_MANIFEST_VERSION = "c7a793816a7a90ed";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -10935,6 +10720,20 @@ function formatUtcTimestamp(value) {
 //#endregion
 //#region ../shared/src/agentMessageText.ts
 /**
+* Prefix every continuation line of a quoted body with `  │ `, so body text
+* never reaches column 0. Structural lines (`[target=…]` / `[1/5 seq=…]` headers,
+* read cursors, footers) always start at column 0, so a line-anchored reader
+* (`grep '^\['`) cannot be handed a forged one by message content. The `│` is
+* non-whitespace on purpose: a reader that trims each line still sees it. It is
+* the same quote marker as the freshness-hold digest previews. Remove the first
+* four characters after each line separator to recover the original body.
+*/
+const AGENT_BODY_CONTINUATION_PREFIX = "  │ ";
+const AGENT_BODY_LINE_SEPARATOR_GLOBAL = new RegExp(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/.source, "g");
+function indentAgentBodyContinuationLines(text) {
+	return text.replace(AGENT_BODY_LINE_SEPARATOR_GLOBAL, (separator) => `${separator}${AGENT_BODY_CONTINUATION_PREFIX}`);
+}
+/**
 * The target an agent passes back to reply where a message came from:
 * `#channel`, `#channel:shortid`, `dm:@peer`, `dm:@peer:shortid`, or
 * `agent-event:shortid` for third-party app events.
@@ -10977,8 +10776,8 @@ function formatAgentTaskCurrentProjection(projection, taskNumber, neutralize) {
 	const actorType = projection.amendedByType ?? projection.amended_by_type ?? null;
 	const actor = actorName ? neutralizeRefs ? `user:${actorName}` : `@${actorName}` : actorType === "system" ? "system" : "<unresolved>";
 	const amendedAt = projection.amendedAt ?? projection.amended_at ?? null;
-	const lines = [`[${taskNumber ? `task #${taskNumber} ` : "task "}superseded: current projection rev=${revision} source=${source} actor=${actor} time=${amendedAt ? formatUtcTimestamp(amendedAt) : "-"}]`, `Current title: ${neutralizeRefs ? renderPreviewText(projection.title ?? "") : projection.title ?? ""}`];
-	if (projection.description != null) lines.push(`Current description: ${neutralizeRefs ? renderPreviewText(projection.description) : projection.description}`);
+	const lines = [`[${taskNumber ? `task #${taskNumber} ` : "task "}superseded: current projection rev=${revision} source=${source} actor=${actor} time=${amendedAt ? formatUtcTimestamp(amendedAt) : "-"}]`, `Current title: ${indentAgentBodyContinuationLines(neutralizeRefs ? renderPreviewText(projection.title ?? "") : projection.title ?? "")}`];
+	if (projection.description != null) lines.push(`Current description: ${indentAgentBodyContinuationLines(neutralizeRefs ? renderPreviewText(projection.description) : projection.description)}`);
 	return `\n${lines.join("\n")}`;
 }
 /** One received-message line: header bracket + sender + content + suffixes. */
@@ -10997,7 +10796,7 @@ function formatAgentMessageLine(m) {
 	const msgId = m.message_id ? m.message_id.slice(0, 8) : "-";
 	const time = m.timestamp ? formatUtcTimestamp(m.timestamp) : "-";
 	const senderType = ` type=${m.sender_type}`;
-	const content = m.content ?? "";
+	const content = indentAgentBodyContinuationLines(m.content ?? "");
 	const attachSuffix = formatAgentAttachmentSuffix(m.attachments);
 	const taskSuffix = m.task_status ? ` [task #${m.task_number} status=${m.task_status}${formatAgentTaskAssigneeSuffix(m.task_assignee_id, m.task_assignee_name)}]` : "";
 	return `[target=${target} msg=${msgId} time=${time}${senderType}] ${formatAgentSenderHandle(m)}: ${content}${attachSuffix}${taskSuffix}${formatAgentReplyAffordanceSuffix(m)}${formatAgentTaskCurrentProjection(m.task_current_projection)}`;
@@ -11139,6 +10938,64 @@ function projectRaftMessagesInTarget(envelopes, target) {
 	} : envelope)).filter((m) => m !== null);
 }
 //#endregion
+//#region ../shared/src/agentOps/interrupt.ts
+/** Narrow any outcome (SDK or command registry) to an interrupt, without knowing the command. */
+function isInterrupted(outcome) {
+	return Boolean(outcome) && typeof outcome === "object" && outcome.state === "interrupted" && typeof outcome.interrupt === "object";
+}
+/** Build the `unread_messages` interrupt from a Server freshness hold. */
+function unreadMessagesInterrupt(input) {
+	const { hold, target } = input;
+	const withheld = input.withheld === true || hold.freshnessContextMode === "withheld";
+	const heldMessages = withheld ? [] : projectRaftMessagesInTarget(hold.heldMessages ?? [], target);
+	const newMessageCount = withheld ? hold.withheldMessageCount ?? hold.newMessageCount ?? 0 : hold.newMessageCount ?? heldMessages.length;
+	const omittedMessageCount = withheld ? 0 : hold.omittedMessageCount ?? 0;
+	return {
+		reason: "unread_messages",
+		context: input.context,
+		resume: input.resume,
+		...input.cancel ? { cancel: input.cancel } : {},
+		target,
+		newMessageCount,
+		heldMessages,
+		omittedMessageCount,
+		formalMentionCount: withheld ? 0 : hold.mentionAnnotation?.formalMentionCount ?? 0,
+		seenUpToSeq: typeof hold.seenUpToSeq === "number" ? hold.seenUpToSeq : null,
+		withheld,
+		contextComplete: !withheld && heldMessages.length + omittedMessageCount >= newMessageCount
+	};
+}
+/** Resume of an in-process SDK send: no argv (the SDK stores no draft), only the original key to call again with. */
+function inProcessSendResume(idempotencyKey) {
+	return { idempotencyKey };
+}
+/** `raft task claim` argv for a claim request (resume of a held claim). */
+function taskClaimArgv(target, taskNumbers, messageIds, extraArgv = []) {
+	return [
+		"task",
+		"claim",
+		"--target",
+		target,
+		...taskNumbers.flatMap((n) => ["--number", String(n)]),
+		...messageIds.flatMap((id) => ["--message-id", id]),
+		...extraArgv
+	];
+}
+/** `raft task update` argv (resume of a held status update). */
+function taskUpdateArgv(target, taskNumber, status, extraArgv = []) {
+	return [
+		"task",
+		"update",
+		"--target",
+		target,
+		"--number",
+		String(taskNumber),
+		"--status",
+		status,
+		...extraArgv
+	];
+}
+//#endregion
 //#region ../shared/src/agentOps/frontier.ts
 const MAX_EXACT_SEQS = 2500;
 function positiveInt(value) {
@@ -11190,11 +11047,12 @@ var SeenFrontier = class SeenFrontier {
 		}
 	}
 	/**
-	* Attest that the model saw the context a held send/claim returned. Call it
-	* only after the held messages actually reached the model (the SDK cannot
-	* know that, so it never records this implicitly). Returns false and records
-	* nothing when the context was withheld, not fully shown
-	* (`contextComplete: false`), or the Server sent no boundary.
+	* Attest that the model saw the context of an interrupt (`outcome.interrupt`
+	* of an `interrupted` send, claim or task write). Call it only after
+	* `interrupt.context` actually reached the model (the SDK cannot know that,
+	* so it never records this implicitly). Returns false and records nothing
+	* when the context was withheld, not fully shown (`contextComplete: false`),
+	* or the Server sent no boundary.
 	*/
 	recordHeld(held) {
 		if (held.withheld || held.contextComplete === false || held.seenUpToSeq === null) return false;
@@ -11563,7 +11421,8 @@ async function readHistory(client, request, frontier) {
 		...request.after === void 0 ? {} : { after: String(request.after) },
 		...request.before === void 0 ? {} : { before: String(request.before) },
 		...request.around === void 0 ? {} : { around: String(request.around) },
-		...request.limit === void 0 ? {} : { limit: String(request.limit) }
+		...request.limit === void 0 ? {} : { limit: String(request.limit) },
+		...request.consume === false ? { consume: "false" } : {}
 	});
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
@@ -11575,7 +11434,7 @@ async function readHistory(client, request, frontier) {
 		lastReadSeq: typeof data.last_read_seq === "number" ? data.last_read_seq : null,
 		modelSeenUpToSeq: typeof data.model_seen_up_to_seq === "number" ? data.model_seen_up_to_seq : null
 	};
-	recordHistorySeen(frontier, request.target, page, request.around !== void 0);
+	if (request.consume !== false) recordHistorySeen(frontier, request.target, page, request.around !== void 0);
 	return {
 		ok: true,
 		state: page.messages.length > 0 ? "page" : "empty",
@@ -11586,6 +11445,7 @@ async function readHistory(client, request, frontier) {
 }
 /** Attempts for a keyed send whose request never reached the Server (transport failure only). */
 const SEND_TRANSPORT_ATTEMPTS = 3;
+/** Today's held text (unchanged); it is the interrupt's `context` and the outcome's `text`. */
 function heldText(held, action) {
 	const noun = held.newMessageCount === 1 ? "message" : "messages";
 	const head = `Held — ${held.newMessageCount} unread ${noun} in ${held.target}. ${action}`;
@@ -11598,38 +11458,29 @@ function heldText(held, action) {
 	lines.push(`Full text: raft message read --target "${held.target}"`);
 	return lines.join("\n");
 }
-function heldNext(held) {
+/**
+* A Server freshness hold as the `unread_messages` interrupt: the structured
+* details, today's held text as `context`, and the given resume / cancel.
+*/
+function heldInterrupt(target, data, action, resume, cancel) {
+	const interrupt = unreadMessagesInterrupt({
+		target,
+		hold: data,
+		context: "",
+		resume,
+		...cancel ? { cancel } : {}
+	});
 	return {
-		kind: "resend",
-		command: `raft message read --target "${held.target}"`,
-		args: {
-			target: held.target,
-			...held.continuation
-		},
-		why: held.withheld ? "Newer messages exist in this conversation but were withheld; read them, then send again with the same idempotencyKey." : !held.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, then send again with the same idempotencyKey." : "Newer messages arrived in this conversation. Show the held messages to the model, call frontier.recordHeld(held) to attest that, then send again with these args (same idempotencyKey, seen.upToSeq)."
+		...interrupt,
+		context: heldText(interrupt, action)
 	};
 }
-function projectHeld(target, data, idempotencyKey) {
-	const withheld = data.freshnessContextMode === "withheld";
-	const heldMessages = projectRaftMessagesInTarget(data.heldMessages ?? [], target);
-	const seenUpToSeq = typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null;
-	const newMessageCount = withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length;
-	const omittedMessageCount = data.omittedMessageCount ?? 0;
-	const contextComplete = !withheld && heldMessages.length + omittedMessageCount >= newMessageCount;
+function heldSendNext(interrupt) {
 	return {
-		target,
-		idempotencyKey,
-		continuation: {
-			idempotencyKey,
-			...contextComplete && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
-		},
-		newMessageCount,
-		heldMessages,
-		omittedMessageCount,
-		formalMentionCount: data.mentionAnnotation?.formalMentionCount ?? 0,
-		seenUpToSeq,
-		withheld,
-		contextComplete
+		kind: "resend",
+		command: `raft message read --target "${interrupt.target}"`,
+		args: { target: interrupt.target },
+		why: interrupt.withheld ? "Newer messages exist in this conversation but were withheld; read them, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : !interrupt.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : "Newer messages arrived in this conversation. Show interrupt.context to the model, call frontier.recordHeld(interrupt) to attest that, then resume the send (interrupt.resume, same idempotencyKey) or cancel it."
 	};
 }
 function isHeldResponse(data) {
@@ -11656,7 +11507,7 @@ function sentOutcome(target, data) {
 		text: `Message sent to ${target}. Message ID: ${sent.messageId}${warn}`
 	};
 }
-async function sendMessage(client, request, frontier, internal = {}) {
+async function sendMessage(client, request, frontier) {
 	if (!request.target?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target is required to send a message." }));
 	if (typeof request.content !== "string" || !request.content.trim() && !request.attachmentIds?.length) return failureOutcome(opError("INVALID_REQUEST", { message: "Message content (or an attachment) is required." }));
 	const idempotencyKey = request.idempotencyKey?.trim() || crypto.randomUUID();
@@ -11671,42 +11522,20 @@ async function sendMessage(client, request, frontier, internal = {}) {
 		idempotencyKey,
 		...request.mentions?.length ? { mentions: request.mentions } : {},
 		...attestation.seenUpToSeq === void 0 ? {} : { seenUpToSeq: attestation.seenUpToSeq },
-		...attestation.seenExactSeqs.length > 0 ? { seenExactSeqs: attestation.seenExactSeqs.slice(0, 2500) } : {},
-		...internal.sendDraft ? { sendDraft: true } : {},
-		...internal.continueAnyway ? { continueAnyway: true } : {},
-		...internal.reholdCount ? { draftReholdCount: internal.reholdCount } : {}
+		...attestation.seenExactSeqs.length > 0 ? { seenExactSeqs: attestation.seenExactSeqs.slice(0, 2500) } : {}
 	};
 	let result = await client.messages.sendV2(body);
 	for (let attempt = 1; !result.ok && result.error.kind === "transport" && attempt < SEND_TRANSPORT_ATTEMPTS; attempt += 1) result = await client.messages.sendV2(body);
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const reholdCount = (internal.reholdCount ?? 0) + 1;
-		const keyed = {
-			...request,
-			idempotencyKey
-		};
-		const base = projectHeld(request.target, data, idempotencyKey);
-		const held = {
-			...base,
-			resend: (options) => sendMessage(client, options.seen === "held" && base.contextComplete && typeof data.seenUpToSeq === "number" ? {
-				...keyed,
-				seen: {
-					upToSeq: data.seenUpToSeq,
-					exactSeqs: attestation.seenExactSeqs
-				}
-			} : keyed, frontier, {
-				sendDraft: true,
-				reholdCount,
-				...options.seen === "anyway" ? { continueAnyway: true } : {}
-			})
-		};
+		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey));
 		return {
 			ok: true,
-			state: "held",
-			data: held,
-			next: heldNext(held),
-			text: heldText(held, "Your message was not sent.")
+			state: "interrupted",
+			interrupt,
+			next: heldSendNext(interrupt),
+			text: interrupt.context
 		};
 	}
 	if (data.state === "sent") return sentOutcome(request.target, data);
@@ -11883,6 +11712,24 @@ function formatAgentTaskHistory(data) {
 //#endregion
 //#region ../shared/src/agentOps/tasks.ts
 const TASK_CLAIM_REASON_ALREADY_CLAIMED_BY_YOU = "already claimed by you";
+/**
+* A held task call: the interrupt whose resume is the identical command, with
+* no cancel (a held task call saved nothing). `context` is today's held text.
+*/
+function heldTaskInterrupt(target, data, action, after, argv) {
+	const interrupt = unreadMessagesInterrupt({
+		target,
+		hold: data,
+		context: "",
+		resume: { argv }
+	});
+	const noun = interrupt.newMessageCount === 1 ? "message" : "messages";
+	const context = `Held — ${interrupt.newMessageCount} unread ${noun} in ${target}. ${action}\nRead them with: raft message read --target "${target}"\n${after}`;
+	return {
+		...interrupt,
+		context
+	};
+}
 function rowState(result) {
 	if (result.success) return "claimed";
 	if (result.reason === TASK_CLAIM_REASON_ALREADY_CLAIMED_BY_YOU) return "already_yours";
@@ -11923,23 +11770,18 @@ async function claimTasks(client, request) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const { idempotencyKey: _unused, continuation: _c, ...heldBase } = projectHeld(request.target, data, "");
-		const held = {
-			...heldBase,
-			request,
-			retry: () => claimTasks(client, request)
-		};
+		const interrupt = heldTaskInterrupt(request.target, data, "Your task claim was not applied.", "After reviewing, rerun the claim if it is still correct.", taskClaimArgv(request.target, numbers, ids));
 		return {
 			ok: true,
-			state: "held",
-			data: held,
+			state: "interrupted",
+			interrupt,
 			next: {
 				kind: "retry_claim",
 				command: `raft message read --target "${request.target}"`,
-				args: { ...request },
-				why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(held) once the model saw them), then claim again with these args if it is still right."
+				args: { target: request.target },
+				why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume the claim (interrupt.resume) if it is still right."
 			},
-			text: `Held — ${held.newMessageCount} unread ${held.newMessageCount === 1 ? "message" : "messages"} in ${request.target}. Your task claim was not applied.\nRead them with: raft message read --target "${request.target}"\nAfter reviewing, rerun the claim if it is still correct.`
+			text: interrupt.context
 		};
 	}
 	const rows = (data.results ?? []).map((row) => {
@@ -12076,23 +11918,20 @@ async function assignTask(client, request) {
 		text: formatAgentTaskAssigned(request.taskNumber, assignee)
 	};
 }
-function heldTaskWrite(request, data, action, kind) {
-	const { idempotencyKey: _k, continuation: _c, ...base } = projectHeld(request.target, data, "");
-	const held = {
-		...base,
-		request
-	};
+/** A held task write: the interrupt whose resume is the identical command; nothing to cancel. */
+function heldTaskWrite(target, data, action, kind, argv) {
+	const interrupt = heldTaskInterrupt(target, data, action, "After reviewing, repeat the operation if it is still correct.", argv);
 	return {
 		ok: true,
-		state: "held",
-		data: held,
+		state: "interrupted",
+		interrupt,
 		next: {
 			kind,
-			command: `raft message read --target "${request.target}"`,
-			args: { ...request },
-			why: `Unread messages in this channel may change the task; read them (frontier.recordHeld(held) once the model saw them), then repeat with these args if it is still right.`
+			command: `raft message read --target "${target}"`,
+			args: { target },
+			why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume (interrupt.resume) if it is still right."
 		},
-		text: `Held — ${held.newMessageCount} unread ${held.newMessageCount === 1 ? "message" : "messages"} in ${request.target}. ${action}\nRead them with: raft message read --target "${request.target}"\nAfter reviewing, repeat the operation if it is still correct.`
+		text: interrupt.context
 	};
 }
 async function updateTaskStatus(client, request) {
@@ -12104,7 +11943,7 @@ async function updateTaskStatus(client, request) {
 		status: request.status
 	});
 	if (!result.ok) return failureFromClientResult(result);
-	if (isHeldResponse(result.data)) return heldTaskWrite(request, result.data, "The status change was not applied.", "retry_update_status");
+	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The status change was not applied.", "retry_update_status", taskUpdateArgv(request.target, request.taskNumber, request.status));
 	return {
 		ok: true,
 		state: "updated",
@@ -12116,6 +11955,18 @@ async function updateTaskStatus(client, request) {
 		text: formatAgentTaskStatusUpdated(request.taskNumber, request.status)
 	};
 }
+function taskAmendArgv(request) {
+	return [
+		"task",
+		"amend",
+		"--target",
+		request.target,
+		"--number",
+		String(request.taskNumber),
+		...request.title === void 0 ? [] : ["--title", request.title],
+		...request.description === void 0 ? [] : request.description === null ? ["--clear-description"] : ["--description", request.description]
+	];
+}
 async function amendTask(client, request) {
 	const invalid = requireTaskRef(request);
 	if (invalid) return invalid;
@@ -12127,7 +11978,7 @@ async function amendTask(client, request) {
 		...request.description === void 0 ? {} : { description: request.description }
 	});
 	if (!result.ok) return failureFromClientResult(result);
-	if (isHeldResponse(result.data)) return heldTaskWrite(request, result.data, "The amendment was not applied.", "retry_amend");
+	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The amendment was not applied.", "retry_amend", taskAmendArgv(request));
 	return {
 		ok: true,
 		state: "amended",
@@ -13284,12 +13135,101 @@ async function attachmentComments(client, request) {
 	};
 }
 //#endregion
+//#region ../shared/src/zonedTime.ts
+const MS_PER_SECOND = 1e3;
+const MS_PER_MINUTE = 6e4;
+const MS_PER_DAY = 864e5;
+const formatters = /* @__PURE__ */ new Map();
+function formatterFor(timeZone) {
+	let formatter = formatters.get(timeZone);
+	if (!formatter) {
+		formatter = new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			hourCycle: "h23",
+			era: "short",
+			year: "numeric",
+			month: "numeric",
+			day: "numeric",
+			hour: "numeric",
+			minute: "numeric",
+			second: "numeric"
+		});
+		formatters.set(timeZone, formatter);
+	}
+	return formatter;
+}
+/** Days from 1970-01-01 to the proleptic Gregorian date (H. Hinnant's days_from_civil). */
+function daysFromCivil(year, month, day) {
+	const y = month <= 2 ? year - 1 : year;
+	const era = Math.floor(y / 400);
+	const yoe = y - era * 400;
+	const mp = (month + 9) % 12;
+	const doy = Math.floor((153 * mp + 2) / 5) + day - 1;
+	const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+	return era * 146097 + doe - 719468;
+}
+/** The wall clock as milliseconds on a UTC timeline (no Date, so no 0-99 year quirk or range limit). */
+function wallClockMs(wall) {
+	return daysFromCivil(wall.year, wall.month, wall.day) * MS_PER_DAY + wall.hour * 36e5 + wall.minute * MS_PER_MINUTE + wall.second * MS_PER_SECOND + wall.millisecond;
+}
+function floorMod(value, modulus) {
+	return (value % modulus + modulus) % modulus;
+}
+/** Wall clock of `epochMs` in `timeZone` plus the exact offset in ms (seconds precision). */
+function wallClockAt(epochMs, timeZone) {
+	const parts = {};
+	for (const part of formatterFor(timeZone).formatToParts(epochMs)) parts[part.type] = part.value;
+	const eraYear = Number(parts.year);
+	const wall = {
+		year: /^b/i.test(parts.era ?? "") ? 1 - eraYear : eraYear,
+		month: Number(parts.month),
+		day: Number(parts.day),
+		hour: Number(parts.hour),
+		minute: Number(parts.minute),
+		second: Number(parts.second),
+		millisecond: floorMod(epochMs, MS_PER_SECOND)
+	};
+	return {
+		wall,
+		offsetMs: wallClockMs(wall) - epochMs
+	};
+}
+function offsetMinutesOf(offsetMs) {
+	return -Math.trunc(-offsetMs / MS_PER_MINUTE);
+}
+/** The wall clock and getTimezoneOffset-style offset of `epochMs` in `timeZone`. */
+function zonedInstant(epochMs, timeZone) {
+	const { wall, offsetMs } = wallClockAt(epochMs, timeZone);
+	return {
+		...wall,
+		offsetMinutes: offsetMinutesOf(offsetMs)
+	};
+}
+function pad2(n) {
+	return String(n).padStart(2, "0");
+}
+/** `+08:00` / `-04:00` / `+05:30`, as the CLI has always printed offsets. */
+function formatUtcOffset(offsetMinutes) {
+	const sign = offsetMinutes >= 0 ? "+" : "-";
+	const abs = Math.abs(offsetMinutes);
+	return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+}
+//#endregion
 //#region ../shared/src/agentText/search.ts
-/** Local wall-clock rendering with offset, as the CLI prints search hit times. */
-function formatLocalTimeWithOffset(iso) {
+/**
+* Wall-clock rendering with offset, as the CLI prints search hit times. With
+* `timeZone` (an IANA name) the time is rendered in that zone; without it, in
+* the process's local zone (the SDK's historical behaviour). The two agree
+* byte for byte when `timeZone` is the process zone.
+*/
+function formatLocalTimeWithOffset(iso, timeZone) {
 	const d = new Date(iso);
 	if (isNaN(d.getTime())) return iso;
 	const pad = (n) => String(n).padStart(2, "0");
+	if (timeZone !== void 0) {
+		const z = zonedInstant(d.getTime(), timeZone);
+		return `${z.year}-${pad(z.month)}-${pad(z.day)} ${pad(z.hour)}:${pad(z.minute)}:${pad(z.second)} ${formatUtcOffset(z.offsetMinutes)}`;
+	}
 	const offsetMinutes = -d.getTimezoneOffset();
 	const sign = offsetMinutes >= 0 ? "+" : "-";
 	const absOffset = Math.abs(offsetMinutes);
@@ -13412,8 +13352,11 @@ function renderSearchPreview(content, query) {
 		trailingOmit
 	].join("");
 }
-/** Search results with <match>/<omit /> preview markup. */
-function formatAgentSearchResults(query, data, offset, sort, limit) {
+/**
+* Search results with <match>/<omit /> preview markup. Hit times render in
+* `timeZone` when given, else in the process's local zone.
+*/
+function formatAgentSearchResults(query, data, offset, sort, limit, timeZone) {
 	const trimmedQuery = query.trim();
 	const oldestShown = data.results?.length ? data.results[data.results.length - 1]?.createdAt : void 0;
 	const nextPageHint = sort === "recent" && oldestShown ? `page with --before ${oldestShown} (pages OLDER only; NOT a complete traversal: stored times are microsecond but this key is millisecond, so rows inside the boundary millisecond can be skipped, and a full page sharing one timestamp can repeat indefinitely; copy the key verbatim)` : `page with --offset ${(offset ?? 0) + (data.results?.length ?? 0)}`;
@@ -13433,7 +13376,7 @@ function formatAgentSearchResults(query, data, offset, sort, limit) {
 			`<result ref="${ref}">`,
 			`Source: ${renderSearchSource(result)}`,
 			`Sender: ${sender}${senderType}`,
-			`Time: ${result.createdAt ? formatLocalTimeWithOffset(result.createdAt) : "-"}`,
+			`Time: ${result.createdAt ? formatLocalTimeWithOffset(result.createdAt, timeZone) : "-"}`,
 			...taskProjection ? [taskProjection] : [],
 			"",
 			"<preview>",
@@ -14144,9 +14087,9 @@ function createRaft(options) {
 			...request,
 			idempotencyKey: pending.idempotencyKey
 		} : request, frontier);
-		if (outcome.ok && outcome.state === "held") session.rememberContinuation({
+		if (outcome.ok && outcome.state === "interrupted" && outcome.interrupt.resume.idempotencyKey) session.rememberContinuation({
 			target: request.target,
-			idempotencyKey: outcome.data.idempotencyKey,
+			idempotencyKey: outcome.interrupt.resume.idempotencyKey,
 			contentHash,
 			heldAt: (/* @__PURE__ */ new Date()).toISOString()
 		});
@@ -14278,4 +14221,4 @@ function createRaft(options) {
 	};
 }
 //#endregion
-export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RAFT_STATE_CONTINUATIONS_PER_TARGET, RAFT_STATE_CONTINUATIONS_TOTAL, RAFT_STATE_SCHEMA, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, bootstrapRaftCredential, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, describeRaftRoute, hasAgentMessageIdentity, hashRaftSendContent, inferAttachmentMimeType, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, parseRaftState, projectRaftMessage, projectRaftMessages, readLatestReadThread, verifyInboxNotice };
+export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RAFT_STATE_CONTINUATIONS_PER_TARGET, RAFT_STATE_CONTINUATIONS_TOTAL, RAFT_STATE_SCHEMA, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, bootstrapRaftCredential, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, describeRaftRoute, hasAgentMessageIdentity, hashRaftSendContent, inferAttachmentMimeType, isInterrupted, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, parseRaftState, projectRaftMessage, projectRaftMessages, readLatestReadThread, verifyInboxNotice };