@namzu/sdk 27.1.0 → 28.0.0

package/src/bridge/a2a/client.ts

@@ -0,0 +1,369 @@
+import { A2A_PROTOCOL_VERSION, TERMINAL_STATES } from '../../constants/a2a/index.js'
+import { A2ATaskSchema } from '../../contracts/a2a.js'
+import type { A2AAgentCard, A2AMessage, A2AMethod, A2ATask } from '../../types/a2a/index.js'
+import type {
+	Delegate,
+	DelegateCapabilities,
+	DelegateRequest,
+	DelegateResult,
+} from '../../types/agent/delegate.js'
+
+/**
+ * The client half of the A2A bridge, as a `Delegate`.
+ *
+ * This kernel could SERVE an agent card and answer `message/send` for two
+ * versions and could not read anybody else's — the bridge was a one-way
+ * door. So the seam added in NZ-PEER-05 had no driven consumer, which is
+ * the state this repo has a ratified rule about: a seam with no caller is
+ * an untested guess at what a caller needs.
+ *
+ * It is deliberately small. Everything about scheduling, cancellation
+ * bookkeeping, sibling policy and outcome predicates already lives in
+ * `DelegatingTaskScheduler`; this only knows how to talk to a peer.
+ */
+
+/** Anything that answers like `fetch`. Injected so a test needs no socket. */
+export type FetchLike = (
+	input: string,
+	init?: {
+		method?: string
+		headers?: Record<string, string>
+		body?: string
+		signal?: AbortSignal
+	},
+) => Promise<{
+	ok: boolean
+	status: number
+	json(): Promise<unknown>
+	text(): Promise<string>
+}>
+
+/** A peer that answered with something that is not an agent card. */
+export class InvalidAgentCardError extends Error {
+	readonly details: { url: string; reason: string }
+
+	constructor(details: { url: string; reason: string }) {
+		super(`The agent card at ${details.url} is not usable: ${details.reason}`)
+		this.name = 'InvalidAgentCardError'
+		this.details = details
+	}
+}
+
+/** A peer speaking a protocol version this kernel does not implement. */
+export class A2AProtocolMismatchError extends Error {
+	readonly details: { url: string; theirs: string; ours: string }
+
+	constructor(details: { url: string; theirs: string; ours: string }) {
+		super(
+			`The peer at ${details.url} speaks A2A ${details.theirs}; this kernel implements ${details.ours}.`,
+		)
+		this.name = 'A2AProtocolMismatchError'
+		this.details = details
+	}
+}
+
+/** The peer answered, and said no. */
+export class A2ARequestError extends Error {
+	readonly details: { method: string; status?: number; code?: string }
+
+	constructor(message: string, details: { method: string; status?: number; code?: string }) {
+		super(message)
+		this.name = 'A2ARequestError'
+		this.details = details
+	}
+}
+
+const majorMinor = (version: string): string => version.split('.').slice(0, 2).join('.')
+
+/**
+ * Read a peer's card, and refuse one this kernel cannot honestly use.
+ *
+ * Two refusals rather than a best effort. A card that does not parse is not
+ * a peer with quirks, it is an unknown service at a URL somebody typed —
+ * and a protocol version this kernel does not implement means every
+ * subsequent request is a guess. Both are found once, at wiring time, which
+ * is the only moment a human is looking; degrade here and the failure moves
+ * to the middle of a delegation with a run waiting on it.
+ *
+ * The version comparison is on major.minor, not the patch. A2A is
+ * pre-1.0, where the minor carries breaking changes — matching on the full
+ * string would refuse a peer over a patch bump that changes nothing.
+ */
+export async function fetchAgentCard(
+	baseUrl: string,
+	opts: { readonly fetch: FetchLike; readonly signal?: AbortSignal },
+): Promise<A2AAgentCard> {
+	const url = `${baseUrl.replace(/\/$/, '')}/.well-known/agent-card.json`
+	const response = await opts.fetch(url, {
+		method: 'GET',
+		headers: { accept: 'application/json' },
+		...(opts.signal ? { signal: opts.signal } : {}),
+	})
+	if (!response.ok) {
+		throw new InvalidAgentCardError({ url, reason: `HTTP ${response.status}` })
+	}
+
+	let body: unknown
+	try {
+		body = await response.json()
+	} catch (err) {
+		throw new InvalidAgentCardError({
+			url,
+			reason: err instanceof Error ? err.message : 'the body is not JSON',
+		})
+	}
+
+	const card = body as Partial<A2AAgentCard>
+	// Checked by hand rather than through a schema, because there is no
+	// `A2AAgentCardSchema` in `contracts/a2a.ts` — the card is a type here
+	// and not a parser. Only the fields this client actually depends on are
+	// required; inventing requirements a peer does not owe us would refuse
+	// working peers.
+	if (typeof card?.name !== 'string' || !Array.isArray(card.supportedInterfaces)) {
+		throw new InvalidAgentCardError({ url, reason: 'no name, or no supportedInterfaces' })
+	}
+	if (card.supportedInterfaces.length === 0) {
+		throw new InvalidAgentCardError({ url, reason: 'supportedInterfaces is empty' })
+	}
+	if (
+		card.protocolVersion &&
+		majorMinor(card.protocolVersion) !== majorMinor(A2A_PROTOCOL_VERSION)
+	) {
+		throw new A2AProtocolMismatchError({
+			url,
+			theirs: card.protocolVersion,
+			ours: A2A_PROTOCOL_VERSION,
+		})
+	}
+	return card as A2AAgentCard
+}
+
+export interface A2ADelegateConfig {
+	/** The id the delegation tools name. See `Delegate.id`. */
+	readonly id: string
+	readonly card: A2AAgentCard
+	readonly fetch: FetchLike
+	/** Headers every request carries — an authorization header, in practice. */
+	readonly headers?: Readonly<Record<string, string>>
+	/** How often to ask `tasks/get` while the peer is still working. */
+	readonly pollIntervalMs?: number
+	/** Give up on a delegation still running after this long. */
+	readonly timeoutMs?: number
+}
+
+const DEFAULT_POLL_MS = 1_000
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000
+
+/**
+ * States this CLIENT will stop polling on — `TERMINAL_STATES` plus
+ * `input-required`, and the difference is not a widening of the same idea.
+ *
+ * `TERMINAL_STATES` is the SERVER's set, and it is right there:
+ * `input-required` is not terminal for a server, because the server is the
+ * side that can receive the input and carry on. It is terminal for this
+ * client, which has no channel to supply it — so the peer will sit in that
+ * state forever and polling it is polling a state that cannot change.
+ *
+ * Reusing the server's set here cost a test timeout to find, and it would
+ * have cost a real delegation the full ten-minute deadline for a peer that
+ * had already answered "which quarter?" in the first second.
+ */
+const WILL_NOT_PROGRESS: ReadonlySet<string> = new Set([...TERMINAL_STATES, 'input-required'])
+
+/** The text of every text part, in order. */
+function textOf(message: A2AMessage | undefined): string | undefined {
+	if (!message) return undefined
+	const text = message.parts
+		.filter((part): part is Extract<typeof part, { kind: 'text' }> => part.kind === 'text')
+		.map((part) => part.text)
+		.join('\n')
+	return text.length > 0 ? text : undefined
+}
+
+/**
+ * A peer's terminal task, as a delegate outcome.
+ *
+ * `input-required` is the interesting one. It is not a failure — the peer
+ * did its work and is waiting for something — but `DelegateResult` has no
+ * state for it, and inventing `completed` would hand the parent a
+ * half-answer as though it were the answer. So it reports `failed` and SAYS
+ * that is what happened, which is the honest reading: this delegate has no
+ * channel to supply the input, so from the parent's side the delegation did
+ * not produce a result.
+ */
+function toDelegateResult(task: A2ATask): DelegateResult {
+	const message = textOf(task.status.message)
+	const artifacts = (task.artifacts ?? [])
+		.map((artifact) => textOf({ role: 'agent', parts: artifact.parts }))
+		.filter((text): text is string => text !== undefined)
+	// Artifacts first: a peer that produced one put its answer there, and the
+	// status message is usually a sentence about the answer rather than the
+	// answer itself.
+	const output = artifacts.length > 0 ? artifacts.join('\n\n') : message
+
+	switch (task.status.state) {
+		case 'completed':
+			return { status: 'completed', ...(output === undefined ? {} : { output }) }
+		case 'canceled':
+			return { status: 'cancelled', ...(output === undefined ? {} : { output }) }
+		case 'input-required':
+			return {
+				status: 'failed',
+				...(output === undefined ? {} : { output }),
+				error: 'The peer is waiting for more input, and this delegate has no channel to supply it.',
+			}
+		default:
+			return {
+				status: 'failed',
+				...(output === undefined ? {} : { output }),
+				error: message ?? `The peer reported ${task.status.state}.`,
+			}
+	}
+}
+
+export class A2ADelegate implements Delegate {
+	readonly id: string
+	readonly capabilities: DelegateCapabilities
+
+	private readonly endpoint: string
+
+	constructor(private readonly config: A2ADelegateConfig) {
+		this.id = config.id
+		const target = config.card.supportedInterfaces.find((i) => i.transport === 'jsonrpc')
+		if (!target) {
+			// Refused at construction. `supportedInterfaces` is what the card
+			// exists to tell us, and a peer offering only gRPC is a peer this
+			// client cannot talk to — discovering that mid-delegation would
+			// waste a run's time on a wiring mistake.
+			throw new InvalidAgentCardError({
+				url: config.card.supportedInterfaces[0]?.url ?? '(no interface)',
+				reason: 'no jsonrpc interface; this client speaks jsonrpc only',
+			})
+		}
+		this.endpoint = target.url
+		this.capabilities = {
+			// Always offered: `tasks/cancel` is in the A2A method set, and a
+			// peer that will not cancel a particular task answers
+			// `TaskNotCancelable`, which surfaces as an error rather than as a
+			// silent no-op.
+			cancel: true,
+			// NOT offered. A2A's `message/send` with an existing task id can
+			// continue a conversation, but this delegate holds one task per
+			// dispatch and `Delegate.continue` is fire-and-forget with no way
+			// to report that the peer refused. Claiming it would be the
+			// silent-no-op the seam refuses.
+			continue: false,
+		}
+	}
+
+	private async rpc(method: A2AMethod, params: unknown, signal?: AbortSignal): Promise<unknown> {
+		const response = await this.config.fetch(this.endpoint, {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				accept: 'application/json',
+				...this.config.headers,
+			},
+			body: JSON.stringify({ jsonrpc: '2.0', id: `${method}-${this.id}`, method, params }),
+			...(signal ? { signal } : {}),
+		})
+		if (!response.ok) {
+			throw new A2ARequestError(`${method} failed with HTTP ${response.status}`, {
+				method,
+				status: response.status,
+			})
+		}
+		const body = (await response.json()) as {
+			result?: unknown
+			error?: { code?: string | number; message?: string }
+		}
+		if (body.error) {
+			throw new A2ARequestError(body.error.message ?? `${method} was refused`, {
+				method,
+				...(body.error.code === undefined ? {} : { code: String(body.error.code) }),
+			})
+		}
+		return body.result
+	}
+
+	private parseTask(raw: unknown, method: A2AMethod): A2ATask {
+		const parsed = A2ATaskSchema.safeParse(raw)
+		if (!parsed.success) {
+			// Validated rather than trusted. This is a foreign service's reply
+			// being turned into a result the model will read as an answer, and
+			// the difference between a malformed task and a task in a state we
+			// mishandle is exactly what a parse tells us.
+			throw new A2ARequestError(`${method} returned something that is not an A2A task`, {
+				method,
+			})
+		}
+		return parsed.data as A2ATask
+	}
+
+	async dispatch(
+		request: DelegateRequest,
+		opts: { readonly signal?: AbortSignal },
+	): Promise<DelegateResult> {
+		const sent = this.parseTask(
+			await this.rpc(
+				'message/send',
+				{ message: { role: 'user', parts: [{ kind: 'text', text: request.prompt }] } },
+				// Deliberately NOT `opts.signal`. An abort must reach the peer as
+				// a `tasks/cancel`, and it cannot if the request that learns the
+				// task id is itself aborted — the delegation would be left
+				// running on the peer's side, billed, with nothing here holding
+				// an id that could stop it.
+			),
+			'message/send',
+		)
+
+		// The abort tells the PEER to stop. Aborting only our poll loop leaves
+		// the peer working and holding whatever the task holds; a cancel has
+		// to reach the side doing the work. Fire-and-forget with the failure
+		// swallowed: this is best-effort courtesy on a path that is already
+		// unwinding, and a peer that refuses the cancel must not turn the
+		// parent's cancellation into an exception.
+		const tellThePeer = () => {
+			void this.rpc('tasks/cancel', { id: sent.id }).catch(() => {})
+		}
+		opts.signal?.addEventListener('abort', tellThePeer, { once: true })
+		if (opts.signal?.aborted) tellThePeer()
+
+		try {
+			const deadline = Date.now() + (this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+			let task = sent
+			while (!WILL_NOT_PROGRESS.has(task.status.state)) {
+				if (opts.signal?.aborted) {
+					// The peer has been told. Reported as cancelled rather than
+					// polled to a terminal state, because the parent has stopped
+					// waiting and the answer is no longer wanted.
+					return { status: 'cancelled' }
+				}
+				if (Date.now() > deadline) {
+					return {
+						status: 'failed',
+						error: `The peer was still ${task.status.state} after ${this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms.`,
+					}
+				}
+				await sleep(this.config.pollIntervalMs ?? DEFAULT_POLL_MS, opts.signal)
+				task = this.parseTask(
+					await this.rpc('tasks/get', { id: sent.id }, opts.signal),
+					'tasks/get',
+				)
+			}
+			return toDelegateResult(task)
+		} finally {
+			opts.signal?.removeEventListener('abort', tellThePeer)
+		}
+	}
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve) => {
+		const timer = setTimeout(resolve, ms)
+		signal?.addEventListener('abort', () => {
+			clearTimeout(timer)
+			resolve()
+		})
+	})
+}

package/src/bridge/a2a/mapper.ts

@@ -82,6 +82,12 @@ const MAPPING: {
 	// Capability degradation is host-facing diagnostics, not A2A task state.
 	capability_warning: null,
 
+	// Who approves on THIS side is an operator fact about this host, not a
+	// transition in the task the peer is watching. Forwarding it would also
+	// tell a remote caller how loosely its work is being supervised, which
+	// is not the peer's business.
+	approval_policy_changed: null,
+
 	iteration_started: (e, ctx) =>
 		statusEvent(e.runId, 'running', false, ctx, {
 			role: 'agent',
@@ -203,7 +209,18 @@ const MAPPING: {
 	iteration_completed: null,
 	// Context management is kernel-internal bookkeeping; A2A peers model a
 	// task lifecycle, not the host runtime's memory strategy.
+	// What THIS runtime asked its model is not a fact about the task a peer
+	// is tracking, and it is the largest single payload the kernel emits.
+	request_envelope: null,
+	// Declined. This carries whole message bodies including tool output, and
+	// a peer models a task lifecycle — shipping a run's deleted history over
+	// an external wire by default is a disclosure nobody asked for.
+	compaction_shed: null,
 	compaction_completed: null,
+	// Same reason as the two below: which of this runtime's context-relief
+	// strategies fired is a property of how it manages its own window, and a
+	// peer modelling a task lifecycle can act on none of them.
+	compaction_tool_results_cleared: null,
 	// Compaction, succeeded or declined, is a property of how this runtime
 	// manages its own context. A peer models a task lifecycle and cannot act on
 	// either outcome.

package/src/bridge/acp/filesystem.ts

@@ -0,0 +1,63 @@
+import type { Sandbox } from '../../types/sandbox/index.js'
+
+/**
+ * The editor's buffers, as the filesystem the agent sees.
+ *
+ * The concrete problem: a user has unsaved changes open. The agent reads the
+ * file from disk, sees a version nobody is looking at, and edits THAT — so
+ * the model's patch is computed against text the user already replaced, and
+ * applying it either conflicts or silently reverts their work.
+ *
+ * A client that declares the filesystem capability is telling this agent
+ * that disk may be stale and that it can answer for the live content. So
+ * reads and writes go to the client and everything else is untouched.
+ *
+ * **A decorator, not a `Sandbox` of its own.** A sandbox is an execution
+ * boundary as much as a filesystem — `exec`, `destroy`, `rootDir`, a network
+ * policy — and a client-backed object that implemented only the file methods
+ * would take `bash` away from a session that had it. Every other member
+ * delegates, and this file names only the two it replaces.
+ */
+
+/** What the client can answer, once it has declared the capability. */
+export interface AcpClientFilesystem {
+	readTextFile(path: string): Promise<string>
+	writeTextFile(path: string, content: string): Promise<void>
+}
+
+/**
+ * Wrap `inner` so file reads and writes ask the client.
+ *
+ * Returns `inner` unchanged when there is no client filesystem, so a caller
+ * does not have to branch: the absence of the capability is the ordinary
+ * case and it should not produce a different code path at every call site.
+ */
+export function clientBackedSandbox(
+	inner: Sandbox,
+	client: AcpClientFilesystem | undefined,
+): Sandbox {
+	if (!client) return inner
+
+	return new Proxy(inner, {
+		get(target, property, receiver) {
+			if (property === 'readFile') {
+				return async (path: string): Promise<Buffer> =>
+					Buffer.from(await client.readTextFile(path), 'utf-8')
+			}
+			if (property === 'writeFile') {
+				return async (path: string, content: string | Buffer): Promise<void> => {
+					await client.writeTextFile(
+						path,
+						typeof content === 'string' ? content : content.toString('utf-8'),
+					)
+				}
+			}
+			// A Proxy rather than a spread, so a member added to `Sandbox` after
+			// this file was written still reaches the real sandbox. A spread
+			// copies what existed the day it was written and silently drops the
+			// rest — the same defect as a hand-listed re-export.
+			const value = Reflect.get(target, property, receiver)
+			return typeof value === 'function' ? value.bind(target) : value
+		},
+	})
+}

package/src/bridge/acp/index.ts

@@ -0,0 +1,11 @@
+export { ACPServer } from './server.js'
+export type { AcpAgentGateway, AcpServerOptions } from './server.js'
+export { clientBackedSandbox } from './filesystem.js'
+export type { AcpClientFilesystem } from './filesystem.js'
+export { ACP_DEFAULT_REJECTION, toResumeDecision } from './permission.js'
+export type {
+	AcpPermissionAsker,
+	AcpPermissionOutcome,
+	AcpPermissionRequest,
+} from './permission.js'
+export { toAcpSessionUpdate, toAcpStopReason } from './update.js'

package/src/bridge/acp/permission.ts

@@ -0,0 +1,71 @@
+import type { HITLResumeDecision, ToolCallSummary } from '../../types/hitl/index.js'
+
+/**
+ * A tool batch, on its way to a human sitting in front of an editor.
+ *
+ * The kernel's own `ToolCallSummary`, not a re-declared one: this is the
+ * shape the HITL path already produces, and a copy would be a second
+ * definition of "which calls am I being asked about" that can drift from the
+ * one the run actually parked on.
+ */
+export interface AcpPermissionRequest {
+	readonly sessionId: string
+	readonly toolCalls: readonly ToolCallSummary[]
+}
+
+/**
+ * What the human said.
+ *
+ * Three outcomes, matching what a human can actually mean about a batch of
+ * calls: run it, run it and stop asking, or do not run it and here is why.
+ * `reject` carries optional feedback because a denial with a reason is the
+ * one a model can act on — "no, use the staging bucket" redirects a run,
+ * where a bare denial only ends it.
+ */
+export type AcpPermissionOutcome =
+	| { readonly kind: 'approve' }
+	| { readonly kind: 'approve_all' }
+	| { readonly kind: 'reject'; readonly feedback?: string }
+
+export type AcpPermissionAsker = (request: AcpPermissionRequest) => Promise<AcpPermissionOutcome>
+
+/**
+ * The default a denial carries when the client sent none.
+ *
+ * Something rather than an empty string, because this text reaches the MODEL
+ * as a `reject_tools` feedback and an empty one reads as a tool that failed
+ * for no reason — the model retries it. Naming the human is what makes the
+ * next turn take a different path.
+ */
+export const ACP_DEFAULT_REJECTION = 'The person operating this session declined these tool calls.'
+
+/**
+ * One outcome as a kernel decision.
+ *
+ * A table, in one place, because the mapping is where a permission bridge
+ * goes wrong: `approve_all` collapsing into `approve` means the latch never
+ * takes and the human is asked again on every batch; `reject` collapsing
+ * into `continue` means the denial is DISCARDED and the calls run anyway.
+ * Both are silent.
+ */
+export function toResumeDecision(
+	outcome: AcpPermissionOutcome,
+	grantKeys: readonly string[],
+): HITLResumeDecision {
+	switch (outcome.kind) {
+		case 'approve':
+			// No `remember`. Consent is not transferable: this batch was
+			// approved, and the next one is a new question.
+			return { action: 'approve_tools' }
+		case 'approve_all':
+			// The keys ARE the latch. `approve_tools` with nothing remembered is
+			// indistinguishable from a plain approve, which is exactly how an
+			// "approve all" that never takes gets shipped.
+			return { action: 'approve_tools', remember: grantKeys }
+		case 'reject':
+			return {
+				action: 'reject_tools',
+				feedback: outcome.feedback?.trim() || ACP_DEFAULT_REJECTION,
+			}
+	}
+}