@namzu/sdk 49.0.0 → 50.1.0

package/src/pals/communication/tools.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod'
+import { defineTool } from '../../tools/defineTool.js'
+import type { ToolContext, ToolDefinition } from '../../types/tool/index.js'
+import { addressSchema, hash, intentSchema, sourceSchema } from './schema.js'
+import type { PalMessageSender, PalMessageSenderContext } from './types.js'
+
+/** Only discovery information explicitly approved for the executing Pal. */
+export interface PalMessagingRecipient {
+	readonly palId: string
+	readonly name: string
+	readonly description?: string
+}
+
+export interface PalMessagingToolsOptions {
+	/** Created by the host from the same captured source; never selected by the model. */
+	readonly sender: PalMessageSender
+	readonly source: PalMessageSenderContext
+	/** Required live admission check, including current pause/retirement and execution scope. */
+	readonly assertCurrentAdmission: (context: ToolContext) => void | Promise<void>
+	/** Required current visibility policy. No Pal-store or directory-listing fallback exists. */
+	readonly listAuthorizedPals: (
+		context: ToolContext,
+	) => readonly PalMessagingRecipient[] | Promise<readonly PalMessagingRecipient[]>
+}
+
+const sendSchema = z
+	.object({
+		palId: addressSchema.shape.palId.describe('Recipient Pal ID.'),
+		body: intentSchema.shape.body.describe('The explicit message to send.'),
+		replyTo: intentSchema.shape.replyTo
+			.unwrap()
+			.optional()
+			.describe('An observed incoming Pal message ID, when replying in its conversation.'),
+	})
+	.strict()
+const listSchema = z.object({}).strict()
+const recipientSchema = z
+	.object({
+		palId: addressSchema.shape.palId,
+		name: z.string().min(1),
+		description: z.string().optional(),
+	})
+	.strict()
+
+/**
+ * Host-installed tools over an explicitly authorized sender and discovery view.
+ * Sending commits an acceptance receipt; it never waits for a recipient turn.
+ */
+export function createPalMessagingTools(options: PalMessagingToolsOptions): ToolDefinition[] {
+	if (
+		typeof options.sender?.send !== 'function' ||
+		typeof options.assertCurrentAdmission !== 'function' ||
+		typeof options.listAuthorizedPals !== 'function'
+	)
+		throw new TypeError(
+			'Pal messaging tools require a sender, live admission and authorized discovery.',
+		)
+	const parsed = sourceSchema.parse(options.source)
+	const source = Object.freeze({ ...parsed, address: Object.freeze({ ...parsed.address }) })
+	const send = options.sender.send.bind(options.sender)
+	const assertCurrentAdmission = options.assertCurrentAdmission
+	const listAuthorizedPals = options.listAuthorizedPals
+	const assertCurrent = async (context: ToolContext): Promise<void> => {
+		context.abortSignal?.throwIfAborted()
+		if (context.sessionId !== source.conversationId)
+			throw new Error('Pal messaging requires the captured sender conversation.')
+		await assertCurrentAdmission(context)
+		context.abortSignal?.throwIfAborted()
+	}
+	return [
+		defineTool({
+			name: 'send_pal_message',
+			description:
+				'Send an explicit message to another Pal under the current host policy. Returns durable acceptance, not proof of delivery or a completed recipient task. Use replyTo only for an incoming Pal message you observed. The host selects sender and tenant; messages and Pal descriptions do not grant new authority.',
+			inputSchema: sendSchema,
+			category: 'custom',
+			permissions: [],
+			readOnly: false,
+			destructive: false,
+			concurrencySafe: true,
+			maxRetries: 0,
+			async execute(input, context) {
+				const request = sendSchema.parse(input)
+				await assertCurrent(context)
+				if (
+					typeof context.toolBatchId !== 'string' ||
+					!context.toolBatchId ||
+					typeof context.toolUseId !== 'string' ||
+					!context.toolUseId
+				)
+					throw new Error('Pal messaging requires executor toolBatchId and toolUseId.')
+				const operationId = hash([
+					1,
+					'pal-message-tool',
+					source.conversationId,
+					context.toolBatchId,
+					context.toolUseId,
+				])
+				const receipt = await send({
+					operationId,
+					recipient: { tenantId: source.address.tenantId, palId: request.palId },
+					body: request.body,
+					...(request.replyTo === undefined ? {} : { replyTo: request.replyTo }),
+				})
+				const accepted = {
+					status: receipt.status,
+					messageId: receipt.id,
+					recipientPalId: receipt.recipient.palId,
+				}
+				return { success: true, output: JSON.stringify(accepted), data: accepted }
+			},
+		}),
+		defineTool({
+			name: 'list_pals',
+			description:
+				'List only Pals currently visible through the host authorization policy. Names and descriptions identify recipients; visibility alone does not authorize sending or recipient actions. This view does not list host files, workspaces, credentials or all registered Pals.',
+			inputSchema: listSchema,
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			async execute(input, context) {
+				listSchema.parse(input)
+				await assertCurrent(context)
+				const visible = await listAuthorizedPals(context)
+				await assertCurrent(context)
+				const pals = visible.map((pal) =>
+					recipientSchema.parse({
+						palId: pal.palId,
+						name: pal.name,
+						...(pal.description === undefined ? {} : { description: pal.description }),
+					}),
+				)
+				return { success: true, output: JSON.stringify({ pals }), data: { pals } }
+			},
+		}),
+	]
+}

package/src/pals/communication/types.ts

@@ -0,0 +1,227 @@
+import type { SessionLog } from '../../store/session-log/core.js'
+import type { ProjectId, SessionId, TenantId, TurnId } from '../../types/ids/index.js'
+import type {
+	DurableInboundSource,
+	InboundDeliveryReceipt,
+	InboundDeliveryRef,
+} from '../../types/message/inbound-delivery.js'
+import type { PalDefinition, PalStore } from '../types.js'
+
+export interface PalAddress {
+	readonly tenantId: TenantId
+	readonly palId: string
+}
+
+/** One sender conversation opens a distinct, authorized recipient conversation. */
+export interface PalRouteKey {
+	readonly v: 1
+	readonly kind: 'pal'
+	readonly sender: PalAddress
+	readonly senderConversationId: SessionId
+	readonly recipient: PalAddress
+	readonly dialogKey: string
+}
+
+export interface PalRouteBinding {
+	readonly id: string
+	readonly key: PalRouteKey
+	readonly sessionId: SessionId
+	readonly profileRevision: number
+	readonly revision: number
+	readonly phase: 'reserved' | 'active'
+}
+
+export interface PalMessageSenderContext {
+	readonly address: PalAddress
+	readonly conversationId: SessionId
+	readonly profileRevision: number
+}
+
+/** An audit reference, never a bearer credential or continuing grant. */
+export interface PalMessageGrant {
+	readonly id: string
+	readonly revision: string
+}
+
+export interface PalMessageIntent {
+	readonly id: string
+	readonly digest: string
+	readonly operationId: string
+	readonly source: PalMessageSenderContext
+	readonly recipient: PalAddress
+	readonly routeKey: PalRouteKey
+	readonly body: string
+	readonly replyTo: string | null
+	readonly grant: PalMessageGrant
+	readonly createdAt: number
+}
+
+export interface PalDeliveryClaim {
+	readonly id: string
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly generation: number
+	/** Exact rendered context retained for recovery, including its delimiter nonce. */
+	readonly content: string
+}
+
+export interface PalInboxMessage extends PalMessageIntent {
+	readonly ordinal: number
+	readonly routeId: string
+	readonly phase: 'pending' | 'claimed' | 'recorded'
+	readonly claim: PalDeliveryClaim | null
+	readonly receipt: InboundDeliveryReceipt | null
+}
+
+export interface PalMessageReceipt {
+	readonly id: string
+	readonly digest: string
+	readonly recipient: PalAddress
+	readonly routeId: string
+	readonly sessionId: SessionId
+	readonly ordinal: number
+	readonly status: 'accepted'
+}
+
+export interface PalCommunicationSnapshot {
+	readonly recipient: PalAddress
+	readonly revision: number
+	readonly routes: readonly PalRouteBinding[]
+	readonly messages: readonly PalInboxMessage[]
+}
+
+/** These methods are a trusted host/store port, never model-visible evidence tools. */
+export interface PalCommunicationStore {
+	read(recipient: PalAddress): Promise<PalCommunicationSnapshot | null>
+	accept(
+		intent: PalMessageIntent,
+		recipientRevision: number,
+		conversationId?: SessionId,
+	): Promise<PalMessageReceipt>
+	route(key: PalRouteKey): Promise<PalRouteBinding | null>
+	activate(binding: PalRouteBinding, context: PalVerificationContext): Promise<PalRouteBinding>
+	claim(
+		binding: PalRouteBinding,
+		request: {
+			readonly turnId: TurnId
+			readonly generation: number
+			readonly content: (message: PalInboxMessage) => string
+		},
+	): Promise<PalInboxMessage | null>
+	recorded(
+		message: PalInboxMessage,
+		receipt: InboundDeliveryReceipt,
+		context: PalVerificationContext,
+	): Promise<PalInboxMessage>
+	/** Only a trusted verifier that has fenced the prior writer may invoke this. */
+	releaseUnrecorded(
+		message: PalInboxMessage,
+		context: PalVerificationContext,
+	): Promise<PalInboxMessage>
+}
+
+/** A host ensures the exact pinned Pal root claim; opening does not repair a foreign log. */
+export interface PalConversationAccess {
+	readonly log: SessionLog
+	readonly projectId: ProjectId
+}
+
+export interface PalVerificationContext {
+	readonly binding: PalRouteBinding
+	readonly access: PalConversationAccess
+	readonly definition: PalDefinition
+}
+
+export interface PalMessageHostPort {
+	ensureConversation(binding: PalRouteBinding, signal: AbortSignal): Promise<void>
+	openConversation(binding: PalRouteBinding, signal: AbortSignal): Promise<PalConversationAccess>
+	/** Hint only; failure cannot revoke a committed acceptance receipt. */
+	notify?(recipient: PalAddress): void | Promise<void>
+	wait?(binding: PalRouteBinding, signal: AbortSignal): Promise<void>
+	/** Host owns normal query execution and real Pal/computer admission. */
+	runConversation(
+		binding: PalRouteBinding,
+		source: DurableInboundSource,
+		signal: AbortSignal,
+	): Promise<void>
+}
+
+export type PalMessageAuthorization =
+	| { readonly allow: true; readonly grant: PalMessageGrant }
+	| { readonly allow: false; readonly reason: string }
+
+export interface PalAuthorizationRequest {
+	readonly phase: 'send' | 'deliver' | 'wake'
+	readonly source: PalMessageSenderContext
+	readonly recipient: PalAddress
+	readonly routeKey: PalRouteKey
+	readonly body: string
+	readonly replyTo: string | null
+}
+
+export interface PalMessageBrokerOptions {
+	readonly store: PalCommunicationStore
+	readonly pals: PalStore
+	/** Required current sender disclosure AND recipient receive policy. No permissive default. */
+	readonly authorize: (request: PalAuthorizationRequest) => Promise<PalMessageAuthorization>
+	readonly host?: PalMessageHostPort
+	readonly now?: () => number
+	readonly onNotificationError?: (
+		error: unknown,
+		receipt: PalMessageReceipt,
+	) => void | Promise<void>
+}
+
+export interface PalMessageSender {
+	/** Stable captured tool-call/outbox identity; retries must retain it. */
+	send(input: {
+		readonly operationId: string
+		readonly recipient: PalAddress
+		readonly body: string
+		readonly dialogKey?: string
+		readonly replyTo?: string
+	}): Promise<PalMessageReceipt>
+}
+
+export type PalDispatchOutcome =
+	| { readonly status: 'idle'; readonly reason: 'empty' | 'unresolved' }
+	| { readonly status: 'blocked'; readonly reason: string }
+	| { readonly status: 'ran'; readonly binding: PalRouteBinding }
+
+export interface PalInboxSourceOptions {
+	readonly store: PalCommunicationStore
+	readonly pals: PalStore
+	readonly binding: PalRouteBinding
+	readonly host: PalMessageHostPort
+	readonly authorize: PalMessageBrokerOptions['authorize']
+}
+
+export const PAL_MESSAGE_NAMESPACE = 'namzu-pal-message/1'
+
+export function palMessageRef(message: Pick<PalInboxMessage, 'id' | 'digest'>): InboundDeliveryRef {
+	return { namespace: PAL_MESSAGE_NAMESPACE, id: message.id, digest: message.digest }
+}
+
+export function authorizationRequest(
+	message: PalMessageIntent,
+	phase: PalAuthorizationRequest['phase'],
+): PalAuthorizationRequest {
+	return {
+		phase,
+		source: message.source,
+		recipient: message.recipient,
+		routeKey: message.routeKey,
+		body: message.body,
+		replyTo: message.replyTo,
+	}
+}
+
+export function sameAddress(one: PalAddress, two: PalAddress): boolean {
+	return one.tenantId === two.tenantId && one.palId === two.palId
+}
+
+export function currentRecipient(pals: PalStore, binding: PalRouteBinding): PalDefinition {
+	const pal = pals.get(binding.key.recipient.palId)
+	if (!pal || pal.paused) throw new Error('Recipient Pal is paused or unavailable.')
+	return pals.getRevision(pal.id, binding.profileRevision)
+}

package/src/pals/communication/verify.ts

@@ -0,0 +1,220 @@
+import { isDeepStrictEqual } from 'node:util'
+import type { SessionLogEntry } from '../../store/session-log/chain.js'
+import type { SessionLogRead } from '../../store/session-log/core.js'
+import type { InboundDeliveryReceipt } from '../../types/message/inbound-delivery.js'
+import type { UserMessage } from '../../types/message/index.js'
+import {
+	checkedIngressIntent,
+	ingressBindingSchema,
+	ingressInboxSchema,
+	ingressReceiptSchema,
+	ingressRouteId,
+} from './ingress-schema.js'
+import {
+	type PalIngressInboxMessage,
+	type PalIngressVerificationContext,
+	ingressMessageRef,
+	ingressRuntimeContextKind,
+} from './ingress-types.js'
+import { freezeCommunicationValue } from './schema.js'
+import type { PalInboxMessage, PalVerificationContext } from './types.js'
+
+function capturedContext(input: PalIngressVerificationContext): PalIngressVerificationContext {
+	return {
+		binding: freezeCommunicationValue(ingressBindingSchema.parse(input.binding)),
+		definition: { ...input.definition },
+		access: { ...input.access },
+	}
+}
+
+/** Read original records, never compacted model history or model-supplied evidence. */
+export async function verifyIngressConversation(
+	inputContext: PalIngressVerificationContext,
+	through?: InboundDeliveryReceipt['through'],
+): Promise<SessionLogRead> {
+	const context = capturedContext(inputContext)
+	const { binding, access, definition } = context
+	if (
+		access.log.sessionId !== binding.sessionId ||
+		definition.id !== binding.key.recipient.palId ||
+		definition.revision !== binding.profileRevision
+	)
+		throw new Error('Foreign Pal conversation access.')
+	const read = await access.log.readAll({
+		mode: 'strict',
+		...(through ? { expectHead: through.pointer } : {}),
+	})
+	if (!read.intact || read.tornBytes !== 0)
+		throw new Error('Pal conversation has incomplete delivery evidence.')
+	if (through) {
+		const covered = read.entries.find((entry) => entry.record.seq === through.pointer.seq)
+		if (
+			!covered ||
+			covered.record.gen !== through.gen ||
+			through.bytes !== through.pointer.offset + through.pointer.length
+		)
+			throw new Error('Delivery receipt does not name the actual verified log head.')
+	}
+	const first = read.entries[0]?.record
+	if (
+		first?.type !== 'session_started' ||
+		first.parent ||
+		first.forkedFrom ||
+		first.sessionId !== binding.sessionId ||
+		first.projectId !== access.projectId ||
+		first.tenantId !== binding.key.recipient.tenantId ||
+		first.cwd !== definition.workspace ||
+		first.origin?.protocol !== 'desktop' ||
+		first.origin.externalSessionId !==
+			JSON.stringify(['namzu-pal', definition.id, definition.revision, binding.sessionId])
+	)
+		throw new Error('Conversation is not claimed by the exact Pal and profile revision.')
+	return read
+}
+
+function checkedDelivery(
+	input: PalIngressInboxMessage,
+	context: PalIngressVerificationContext,
+): PalIngressInboxMessage {
+	const message = ingressInboxSchema.parse(input) as PalIngressInboxMessage
+	const raw = { ...message } as Record<string, unknown>
+	for (const key of ['ordinal', 'routeId', 'phase', 'claim', 'receipt']) delete raw[key]
+	checkedIngressIntent(raw)
+	if (
+		message.routeId !== ingressRouteId(message.routeKey) ||
+		context.binding.id !== ingressRouteId(context.binding.key) ||
+		context.binding.id !== message.routeId ||
+		!isDeepStrictEqual(context.binding.key, message.routeKey) ||
+		!message.claim ||
+		message.claim.sessionId !== context.binding.sessionId
+	)
+		throw new Error('Foreign delivery route or claim.')
+	return message
+}
+
+async function matches(
+	entry: SessionLogEntry,
+	message: PalIngressInboxMessage,
+	context: PalIngressVerificationContext,
+): Promise<boolean> {
+	const record = entry.record
+	if (
+		!message.claim ||
+		record.type !== 'message' ||
+		record.role !== 'user' ||
+		record.turnId !== message.claim.turnId ||
+		record.gen !== message.claim.generation
+	)
+		return false
+	const content = (
+		record.spill ? JSON.parse(await context.access.log.readSpill(record.spill)) : record.content
+	) as Partial<UserMessage> & { source?: unknown }
+	if (
+		!content ||
+		content.role !== 'user' ||
+		content.content !== message.claim.content ||
+		!content.source ||
+		typeof content.source !== 'object'
+	)
+		return false
+	const source = content.source as {
+		type?: unknown
+		kind?: unknown
+		deliveryRef?: unknown
+	}
+	return (
+		source.type === 'runtime-context' &&
+		source.kind === ingressRuntimeContextKind(message) &&
+		isDeepStrictEqual(source.deliveryRef, ingressMessageRef(message))
+	)
+}
+
+export async function findRecordedIngressMessage(
+	inputMessage: PalIngressInboxMessage,
+	inputContext: PalIngressVerificationContext,
+	through?: InboundDeliveryReceipt['through'],
+): Promise<{ read: SessionLogRead; entry: SessionLogEntry | null }> {
+	const context = capturedContext(inputContext)
+	const message = checkedDelivery(inputMessage, context)
+	const read = await verifyIngressConversation(context, through)
+	let found: SessionLogEntry | null = null
+	for (const entry of read.entries) {
+		if (!(await matches(entry, message, context))) continue
+		if (found) throw new Error('Pal delivery appears more than once in the conversation log.')
+		found = entry
+	}
+	return { read, entry: found }
+}
+
+export async function verifyIngressRecorded(
+	inputMessage: PalIngressInboxMessage,
+	inputReceipt: InboundDeliveryReceipt,
+	inputContext: PalIngressVerificationContext,
+): Promise<void> {
+	const context = capturedContext(inputContext)
+	const message = checkedDelivery(inputMessage, context)
+	const receipt = ingressReceiptSchema.parse(inputReceipt)
+	if (
+		!message.claim ||
+		context.binding.id !== message.routeId ||
+		!isDeepStrictEqual(context.binding.key, message.routeKey) ||
+		!isDeepStrictEqual(receipt.ref, ingressMessageRef(message)) ||
+		receipt.claimId !== message.claim.id ||
+		receipt.sessionId !== message.claim.sessionId ||
+		receipt.turnId !== message.claim.turnId ||
+		receipt.through.gen < message.claim.generation
+	)
+		throw new Error('Foreign delivery route or receipt.')
+	const { entry } = await findRecordedIngressMessage(message, context, receipt.through)
+	if (
+		!entry ||
+		entry.record.type !== 'message' ||
+		entry.record.messageId !== receipt.messageId ||
+		entry.record.seq > receipt.through.pointer.seq
+	)
+		throw new Error('No matching recorded message covers this Pal delivery receipt.')
+}
+
+export async function verifyIngressUnrecorded(
+	inputMessage: PalIngressInboxMessage,
+	inputContext: PalIngressVerificationContext,
+): Promise<void> {
+	const context = capturedContext(inputContext)
+	const message = checkedDelivery(inputMessage, context)
+	if (!message.claim || context.binding.id !== message.routeId)
+		throw new Error('Foreign delivery route.')
+	const { entry } = await findRecordedIngressMessage(message, context)
+	if (entry) throw new Error('Recorded delivery cannot be released for retry.')
+	const lease = await context.access.log.lease()
+	const active = await context.access.log.activeTurn()
+	if (!lease || lease.fence <= message.claim.generation || active !== null)
+		throw new Error('Unrecorded delivery has no proof of a fenced and stopped writer.')
+}
+
+/** Legacy Pal-only verification retains its existing signatures. */
+export function verifyConversation(
+	context: PalVerificationContext,
+	through?: InboundDeliveryReceipt['through'],
+): Promise<SessionLogRead> {
+	return verifyIngressConversation(context, through)
+}
+export function findRecordedMessage(
+	message: PalInboxMessage,
+	context: PalVerificationContext,
+	through?: InboundDeliveryReceipt['through'],
+): Promise<{ read: SessionLogRead; entry: SessionLogEntry | null }> {
+	return findRecordedIngressMessage(message, context, through)
+}
+export function verifyRecorded(
+	message: PalInboxMessage,
+	receipt: InboundDeliveryReceipt,
+	context: PalVerificationContext,
+): Promise<void> {
+	return verifyIngressRecorded(message, receipt, context)
+}
+export function verifyUnrecorded(
+	message: PalInboxMessage,
+	context: PalVerificationContext,
+): Promise<void> {
+	return verifyIngressUnrecorded(message, context)
+}

package/src/pals/lifecycle.ts

@@ -0,0 +1,54 @@
+/** Live host facts only: no replay cursor, computer lease, private body or error text. */
+export type PalLifecycleEvent =
+	| { readonly type: 'computer.starting'; readonly palId: string }
+	| {
+			readonly type: 'computer.ready'
+			readonly palId: string
+			readonly generation: number
+	  }
+	| {
+			readonly type: 'computer.stopping' | 'computer.stopped' | 'computer.stop-failed'
+			readonly palId: string
+			/** Omitted when releasing an invalid rejected lease, never an accepted generation. */
+			readonly generation?: number
+	  }
+	| {
+			readonly type: 'computer.start-failed'
+			readonly palId: string
+			readonly reason: 'unavailable' | 'cleanup-required'
+	  }
+	| {
+			readonly type: 'admission.acquired'
+			readonly palId: string
+			readonly generation: number
+			readonly conversationId: string
+	  }
+	| {
+			readonly type: 'admission.released'
+			readonly palId: string
+			readonly generation: number
+			readonly conversationId: string
+			readonly reason: 'released' | 'closed'
+	  }
+
+export type PalLifecycleListener = (event: PalLifecycleEvent) => void | Promise<void>
+
+/** Observer failures cannot backpressure or change computer/controller ownership. */
+export class PalLifecycleEmitter {
+	private readonly listeners = new Set<PalLifecycleListener>()
+	on(listener: PalLifecycleListener): () => void {
+		if (typeof listener !== 'function') throw new TypeError('A Pal lifecycle listener is required.')
+		this.listeners.add(listener)
+		return () => {
+			this.listeners.delete(listener)
+		}
+	}
+	emit(event: PalLifecycleEvent): void {
+		const captured = Object.freeze({ ...event })
+		for (const listener of [...this.listeners]) {
+			try {
+				void Promise.resolve(listener(captured)).catch(() => {})
+			} catch {}
+		}
+	}
+}