@namzu/sdk 49.0.0 → 50.1.0

package/src/manager/plan/lifecycle.ts

@@ -34,28 +34,30 @@ export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<Plan
  * (`iteration/phases/context.ts` calls `approve` and `startExecution`),
  * translates its events onto the session event stream (`EventTranslator.wirePlanManager`),
  * and settles it on failure (`runtime/query/result.ts` calls `failPlan`). It
- * never reports a step outcome and never settles a plan that succeeded.
+ * does not infer step outcomes from a turn's final text. The coordinator can
+ * report explicitly bound delegated steps; hosts can also report outcomes.
  *
  * That is a split, not an omission — `drainQuery` hands the manager to the host
  * through `onContextCreated({ planManager })` BEFORE the iteration loop starts,
  * precisely so a host can drive the half the kernel does not. So a grep for
- * callers of `updateStepStatus` or `completePlan` inside this package finds
- * none, and that is not evidence the methods are dead: the callers are hosts,
- * and they are outside the repository. `PlanManager` is exported from
+ * callers of `updateStepStatus` or `completePlan` must account for both the
+ * coordinator and application hosts. `PlanManager` is exported from
  * `public-runtime.ts` for this reason.
  *
  * Recorded here because the absence has already been read once as a dead layer
  * and proposed for deletion. What it would have deleted is a working
  * human-in-the-loop approval gate.
  *
- * The one genuine gap in the split is tracked separately: nothing settles a
- * plan that SUCCEEDED, so its status can reach `failed` or stay `executing`
- * but never `completed`. Fixing that needs a decision about what a
- * kernel-built plan's steps mean, not a guessed status — see `completePlan`.
+ * `completePlan` requires reported outcomes for every step. A plan without
+ * those outcomes stays executing until its owner reports them or abandons it;
+ * an ended turn is not evidence that its steps succeeded.
  */
 export class PlanManager {
 	private currentPlan: Plan | null = null
-	private readonly scope: { readonly sessionId: SessionId; readonly turnId: TurnId }
+	private readonly scope: {
+		readonly sessionId: SessionId
+		readonly turnId: TurnId
+	}
 	private listeners: PlanEventListener[] = []
 	private approvalHandler?: PlanApprovalHandler
 

package/src/manager/session/attribution.ts

@@ -22,7 +22,7 @@ export interface SessionLogAttribution {
 export async function assertSessionLogAttribution(
 	log: SessionLog,
 	scope: SessionLogAttribution,
-	options: { readonly requireStarted?: boolean } = {},
+	options: { readonly requireStarted?: boolean; readonly execution?: 'kernel' } = {},
 ): Promise<boolean> {
 	const requiredFields = ['sessionId', 'projectId', 'tenantId', 'topicId'] as const
 	const missingFields = requiredFields.filter(
@@ -69,7 +69,17 @@ export async function assertSessionLogAttribution(
 	if (opened.topicId === undefined || opened.topicId !== scope.topicId) {
 		fields.push('topicId')
 	}
-	if (fields.length === 0) return true
+	if (fields.length === 0) {
+		if (options.execution === 'kernel' && opened.harness !== undefined) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message:
+					'This session is bound to an external execution engine. Continue it through its harness adapter or start a new Namzu session.',
+				details: { fields: ['harness'] },
+			})
+		}
+		return true
+	}
 
 	throw new NamzuError({
 		code: 'invalid_config',

package/src/manager/session/streamed-message-identity.ts

@@ -0,0 +1,21 @@
+import type { MessageId } from '../../types/ids/index.js'
+import type { AssistantMessage, Message } from '../../types/message/index.js'
+
+// Only the runtime that minted a stream's identity associates a freshly built
+// assistant object here. Caller-authored BaseMessage.id is never an authority.
+const identities = new WeakMap<Message, MessageId>()
+
+export function withStreamedMessageIdentity(
+	message: AssistantMessage,
+	messageId: MessageId,
+): AssistantMessage {
+	identities.set(message, messageId)
+	return message
+}
+
+/** Consume the trusted stream identity once, when this object is first recorded. */
+export function takeStreamedMessageIdentity(message: Message): MessageId | undefined {
+	const identity = identities.get(message)
+	identities.delete(message)
+	return identity
+}

package/src/manager/session/turn-recorder.ts

@@ -54,6 +54,7 @@ import {
 import { asCheckpointId, generateAuditEventId, generateMessageId } from '../../utils/id.js'
 import { childSessionEnded } from '../agent/child-session.js'
 import { assertSessionLogAttribution } from './attribution.js'
+import { takeStreamedMessageIdentity } from './streamed-message-identity.js'
 
 /** Which provider and model a cost is priced against. */
 export interface PricingSubject {
@@ -609,7 +610,7 @@ export class TurnRecorder {
 			}
 			// Claiming a log may repair a torn tail. Refuse a foreign owner
 			// before that mutation, then recheck under the lease below.
-			await assertSessionLogAttribution(this.log, this.#config)
+			await assertSessionLogAttribution(this.log, this.#config, { execution: 'kernel' })
 			if (!options.lease) {
 				const lease = await this.log.claim({
 					holder: this.#leaseHolder,
@@ -657,7 +658,7 @@ export class TurnRecorder {
 					...(options.session.forkedFrom ? { forkedFrom: options.session.forkedFrom } : {}),
 				})
 			} else {
-				await assertSessionLogAttribution(this.log, this.#config)
+				await assertSessionLogAttribution(this.log, this.#config, { execution: 'kernel' })
 			}
 			if (options.session.forkedFrom) {
 				this.#turn.forkedFrom = options.session.forkedFrom
@@ -1057,7 +1058,7 @@ export class TurnRecorder {
 	#idFor(message: Message): MessageId {
 		let id = this.#ids.get(message)
 		if (!id) {
-			id = generateMessageId()
+			id = takeStreamedMessageIdentity(message) ?? generateMessageId()
 			this.#ids.set(message, id)
 		}
 		this.#recorded.set(message, id)

package/src/pals/activity/causality.ts

@@ -0,0 +1,261 @@
+import { createHash } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import { SessionLogChain, type SessionLogEntry } from '../../store/session-log/chain.js'
+import { stableDigest } from '../../utils/hash.js'
+import {
+	activityFactSchema,
+	activityScopeSchema,
+	ingressBindingSchema,
+	ingressInboxSchema,
+	ingressIntentDigest,
+	ingressIntentId,
+	ingressIntentSchema,
+	ingressReceiptSchema,
+} from '../communication/ingress-schema.js'
+import { PAL_OBSERVATION_NAMESPACE, type PalIngressStore } from '../communication/ingress-types.js'
+import type { PalStore } from '../types.js'
+import { projectPalActivity } from './projection.js'
+import type { PalActivityFact, PalActivityScope, PalActivitySourceOptions } from './types.js'
+
+const requestMarkerSchema = z
+	.object({
+		type: z.literal('request_envelope'),
+		iteration: z.literal(1),
+		model: z.string().min(1).max(4096),
+		systemPrompt: z.string(),
+		toolNames: z.array(z.string().min(1).max(512)).max(16_384),
+		toolSchemaDigest: z.string().regex(/^[a-f0-9]{16}$/),
+	})
+	.refine(
+		(value) =>
+			new Set(value.toolNames).size === value.toolNames.length &&
+			(value.toolNames.length > 0 || value.toolSchemaDigest === stableDigest([])),
+	)
+
+export class PalActivityCausalityUnavailableError extends Error {
+	override readonly name = 'PalActivityCausalityUnavailableError'
+	constructor() {
+		super('Complete owned original turn delivery evidence is required before activity publication.')
+	}
+}
+
+export interface PalActivityCausalityOptions {
+	readonly pals: PalStore
+	readonly ingress: PalIngressStore
+	readonly authorize: PalActivitySourceOptions['authorize']
+	readonly openJournal: PalActivitySourceOptions['openJournal']
+	/** Explicit original prefix budgets; exhaustion rejects rather than assuming independence. */
+	readonly maxReadBytes: number
+	readonly maxRecords: number
+}
+
+/**
+ * Build a trusted causality port from original hash-verified records and exact recorded inbox
+ * receipts. It resolves no client cursor and grants no wake/action authority. Early turn facts
+ * wait for the first recorded provider request, after initial durable input acknowledgement.
+ */
+export function createPalActivityCausalityResolver(options: PalActivityCausalityOptions) {
+	const { pals, ingress, authorize, openJournal } = options
+	const maxReadBytes = z.number().int().positive().safe().parse(options.maxReadBytes)
+	const maxRecords = z.number().int().positive().safe().parse(options.maxRecords)
+	if (typeof authorize !== 'function' || typeof openJournal !== 'function')
+		throw new TypeError(
+			'Pal activity causality requires trusted observation and original journal ports.',
+		)
+	return async (
+		inputScope: PalActivityScope,
+		inputFact: PalActivityFact,
+		signal: AbortSignal,
+	): Promise<readonly string[]> => {
+		const scope = Object.freeze(activityScopeSchema.parse(inputScope))
+		const fact = Object.freeze(activityFactSchema.parse(inputFact))
+		const unavailable = (): never => {
+			throw new PalActivityCausalityUnavailableError()
+		}
+		const permission = async () => {
+			signal.throwIfAborted()
+			if ((await authorize(scope, signal)) !== true) unavailable()
+			signal.throwIfAborted()
+		}
+		await permission()
+		const definition = pals.getRevision(scope.palId, scope.profileRevision)
+		const workspace = definition.workspace
+		const journal = await openJournal(scope, signal)
+		signal.throwIfAborted()
+		if (journal.log.sessionId !== scope.sessionId) unavailable()
+		const size = await journal.bytes.size()
+		signal.throwIfAborted()
+		await permission()
+		if (!Number.isSafeInteger(size) || size < 1 || size > maxReadBytes) unavailable()
+		const raw = Uint8Array.from(await journal.bytes.read(0, size))
+		signal.throwIfAborted()
+		if (raw.byteLength !== size || raw.at(-1) !== 10) unavailable()
+		const entries: SessionLogEntry[] = []
+		const chain = new SessionLogChain({ head: null, sessionId: scope.sessionId })
+		let offset = 0
+		let generation = 0
+		while (offset < raw.length) {
+			signal.throwIfAborted()
+			if (entries.length >= maxRecords) unavailable()
+			const end = raw.indexOf(10, offset)
+			if (end < 0) unavailable()
+			let entry: SessionLogEntry
+			try {
+				entry = chain.accept(raw.subarray(offset, end + 1), offset)
+			} catch {
+				return unavailable()
+			}
+			if (entry.record.gen < generation) unavailable()
+			generation = entry.record.gen
+			entries.push(entry)
+			offset = end + 1
+		}
+		const root = entries[0]?.record
+		if (
+			root?.type !== 'session_started' ||
+			root.parent ||
+			root.forkedFrom ||
+			root.tenantId !== scope.tenantId ||
+			root.projectId !== scope.projectId ||
+			root.cwd !== workspace ||
+			root.origin?.protocol !== 'desktop' ||
+			root.origin.externalSessionId !==
+				JSON.stringify(['namzu-pal', scope.palId, scope.profileRevision, scope.sessionId])
+		)
+			unavailable()
+		const scopeHash = createHash('sha256')
+			.update(
+				JSON.stringify([
+					'pal-activity/1',
+					scope.tenantId,
+					scope.projectId,
+					scope.palId,
+					scope.profileRevision,
+					scope.sessionId,
+					workspace,
+				]),
+			)
+			.digest('hex')
+		const original = entries.find((e) => e.record.seq === fact.seq)
+		if (
+			!original ||
+			!isDeepStrictEqual(projectPalActivity(original, scopeHash), fact) ||
+			!fact.turnId
+		)
+			unavailable()
+		const turnId = fact.turnId
+		const firstRequest = entries.find(
+			(e) => e.record.type === 'request_envelope' && e.record.turnId === turnId,
+		)
+		if (!firstRequest) return unavailable()
+		if (!requestMarkerSchema.safeParse(firstRequest.record).success) return unavailable()
+		// Initial inbox delivery follows turn_started; include that intake before classifying early facts.
+		const through = Math.max(fact.seq, firstRequest.record.seq)
+		const state = await ingress.readIngress({ tenantId: scope.tenantId, palId: scope.palId })
+		signal.throwIfAborted()
+		const trail = new Set<string>()
+		for (const entry of entries) {
+			const record = entry.record
+			if (
+				record.seq > through ||
+				record.type !== 'message' ||
+				record.turnId !== turnId ||
+				record.role !== 'user'
+			)
+				continue
+			// Resolving an external spill requires an independently bounded original spill port.
+			if (record.spill) unavailable()
+			const content = record.content as {
+				role?: unknown
+				content?: unknown
+				source?: {
+					type?: unknown
+					kind?: unknown
+					deliveryRef?: { namespace?: unknown; id?: unknown; digest?: unknown }
+				}
+			}
+			const ref = content?.source?.deliveryRef
+			if (
+				content?.source?.kind === 'host-observation' &&
+				ref?.namespace !== PAL_OBSERVATION_NAMESPACE
+			)
+				return unavailable()
+			if (ref?.namespace !== PAL_OBSERVATION_NAMESPACE) continue
+			const storedMessage = state?.messages.find((m) => m.id === ref.id)
+			const parsedMessage = ingressInboxSchema.safeParse(storedMessage)
+			if (!parsedMessage.success) return unavailable()
+			const message = parsedMessage.data
+			const {
+				ordinal: _ordinal,
+				routeId: _routeId,
+				phase: _phase,
+				claim: _claim,
+				receipt: _receipt,
+				...envelope
+			} = message
+			const canonical = ingressIntentSchema.safeParse(envelope)
+			if (
+				!canonical.success ||
+				message.id !== ingressIntentId(canonical.data) ||
+				message.digest !== ingressIntentDigest(canonical.data)
+			)
+				return unavailable()
+			if (
+				!message ||
+				!('kind' in message) ||
+				message.kind !== 'observation' ||
+				message.phase !== 'recorded' ||
+				!message.claim ||
+				!message.receipt ||
+				message.digest !== ref.digest ||
+				message.receipt.ref.namespace !== PAL_OBSERVATION_NAMESPACE ||
+				message.receipt.ref.id !== message.id ||
+				message.receipt.ref.digest !== message.digest ||
+				message.receipt.messageId !== record.messageId ||
+				message.receipt.turnId !== turnId ||
+				message.receipt.sessionId !== scope.sessionId ||
+				message.receipt.claimId !== message.claim.id ||
+				message.claim.turnId !== turnId ||
+				message.claim.sessionId !== scope.sessionId ||
+				message.claim.generation !== record.gen ||
+				message.claim.content !== content.content ||
+				content.role !== 'user' ||
+				content.source?.type !== 'runtime-context' ||
+				content.source.kind !== 'host-observation' ||
+				message.receipt.through.pointer.seq < record.seq
+			)
+				return unavailable()
+			const receipt = ingressReceiptSchema.parse(message.receipt)
+			const covered = entries.find(
+				(candidate) => candidate.record.seq === receipt.through.pointer.seq,
+			)
+			if (
+				!covered ||
+				!isDeepStrictEqual(covered.pointer, receipt.through.pointer) ||
+				covered.record.gen !== receipt.through.gen ||
+				receipt.through.bytes !== covered.pointer.offset + covered.pointer.length
+			)
+				return unavailable()
+			const parsedRoute = ingressBindingSchema.safeParse(
+				state?.routes.find((r) => r.id === message.routeId),
+			)
+			if (!parsedRoute.success) return unavailable()
+			const route = parsedRoute.data
+			if (
+				!route ||
+				route.phase !== 'active' ||
+				!isDeepStrictEqual(route.key, message.routeKey) ||
+				route.sessionId !== scope.sessionId ||
+				route.profileRevision !== scope.profileRevision ||
+				route.key.recipient.palId !== scope.palId ||
+				route.key.recipient.tenantId !== scope.tenantId
+			)
+				unavailable()
+			if (message && 'kind' in message && message.kind === 'observation')
+				for (const id of message.subscriptionTrail) trail.add(id)
+		}
+		await permission()
+		return Object.freeze([...trail])
+	}
+}

package/src/pals/activity/projection.ts

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import type { SessionLogEntry } from '../../store/session-log/chain.js'
+import { isEntityId } from '../../utils/id.js'
+import type { PalActivityFact, PalActivityFactType } from './types.js'
+
+const activityId = z.custom<NonNullable<PalActivityFact['activityId']>>((value) =>
+	isEntityId(value, 'activity'),
+)
+const checkpointId = z.custom<NonNullable<PalActivityFact['checkpointId']>>((value) =>
+	isEntityId(value, 'checkpoint'),
+)
+const toolUseId = z
+	.string()
+	.min(1)
+	.max(512)
+	.regex(/^[A-Za-z0-9_.:-]+$/)
+const activityCreated = z.object({
+	activityId,
+	activityType: z.enum(['tool_call', 'llm_turn', 'sub_agent', 'shell']),
+})
+const activityUpdated = z.object({
+	activityId,
+	status: z.enum(['pending', 'running', 'completed', 'failed', 'cancelled', 'skipped']),
+})
+
+/** Raw journal payloads never escape this closed projection. Unknown types are omitted. */
+export function projectPalActivity(
+	entry: SessionLogEntry,
+	scopeHash: string,
+): PalActivityFact | null {
+	const { record, pointer } = entry
+	let fields: Partial<PalActivityFact>
+	switch (record.type) {
+		case 'turn_started':
+		case 'turn_resuming':
+			fields = { status: 'running' }
+			break
+		case 'turn_paused':
+			fields = { checkpointId: checkpointId.parse(record.checkpointId) }
+			break
+		case 'turn_completed':
+			fields = { status: z.enum(['completed', 'cancelled']).parse(record.settlement.status) }
+			break
+		case 'turn_failed':
+			fields = { status: 'failed' }
+			break
+		case 'activity_created':
+			fields = { ...activityCreated.parse(record), status: 'pending' }
+			break
+		case 'activity_updated':
+			fields = activityUpdated.parse(record)
+			break
+		case 'tool_executing':
+			fields = { toolUseId: toolUseId.parse(record.toolUseId), status: 'running' }
+			break
+		case 'tool_completed':
+			fields = {
+				toolUseId: toolUseId.parse(record.toolUseId),
+				status: z.boolean().parse(record.isError) ? 'failed' : 'completed',
+			}
+			break
+		case 'tool_review_requested':
+			fields = {}
+			break
+		case 'tool_review_completed':
+			fields = {
+				reviewDecision: z.enum(['approved', 'modified', 'rejected']).parse(record.decision),
+			}
+			break
+		case 'checkpoint_created':
+			fields = { checkpointId: checkpointId.parse(record.checkpointId) }
+			break
+		default:
+			return null
+	}
+	return Object.freeze({
+		id: createHash('sha256')
+			.update(JSON.stringify(['pal-activity/1', scopeHash, pointer]))
+			.digest('hex'),
+		type: record.type as PalActivityFactType,
+		sessionId: record.sessionId,
+		...('turnId' in record ? { turnId: record.turnId } : {}),
+		seq: record.seq,
+		generation: record.gen,
+		at: record.ts,
+		...fields,
+	})
+}