@namzu/sdk 48.3.1 → 50.0.0

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,
+	})
+}

package/src/pals/activity/source.ts

@@ -0,0 +1,240 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { parseSessionLogLine } from '../../session/log-hash.js'
+import { SessionLogChain, type SessionLogEntry } from '../../store/session-log/chain.js'
+import { type RecordPointer, SESSION_RECORD_MAX_BYTES } from '../../types/session/records.js'
+import { isEntityId } from '../../utils/id.js'
+import { projectPalActivity } from './projection.js'
+import type {
+	PalActivityCursor,
+	PalActivityFact,
+	PalActivityReadOptions,
+	PalActivityScope,
+	PalActivitySource,
+	PalActivitySourceOptions,
+} from './types.js'
+
+export class PalActivityAccessDeniedError extends Error {
+	override readonly name = 'PalActivityAccessDeniedError'
+	constructor() {
+		super('Current Pal activity observation permission is required.')
+	}
+}
+export class PalActivityIntegrityError extends Error {
+	override readonly name = 'PalActivityIntegrityError'
+	constructor() {
+		super('Pal activity journal ownership or anchor evidence is invalid or incomplete.')
+	}
+}
+export class PalActivityReadLimitError extends Error {
+	override readonly name = 'PalActivityReadLimitError'
+	constructor() {
+		super('The Pal activity byte budget cannot cover another complete record and its anchors.')
+	}
+}
+
+const positive = z.number().int().positive().safe()
+const digest = z.string().regex(/^[a-f0-9]{64}$/)
+const pointer = z
+	.object({
+		seq: positive,
+		offset: z.number().int().nonnegative().safe(),
+		length: positive.max(SESSION_RECORD_MAX_BYTES),
+		sha256: digest,
+	})
+	.strict()
+const scopeSchema = z
+	.object({
+		tenantId: z.custom<PalActivityScope['tenantId']>((v) => isEntityId(v, 'tenant')),
+		projectId: z.custom<PalActivityScope['projectId']>((v) => isEntityId(v, 'project')),
+		sessionId: z.custom<PalActivityScope['sessionId']>((v) => isEntityId(v, 'session')),
+		palId: z.string().uuid(),
+		profileRevision: positive,
+	})
+	.strict()
+const cursorSchema = z
+	.object({
+		v: z.literal(1),
+		scopeHash: digest,
+		root: pointer,
+		after: pointer,
+		generation: z.number().int().nonnegative().safe(),
+	})
+	.strict()
+function samePointer(one: RecordPointer, two: RecordPointer): boolean {
+	return (
+		one.seq === two.seq &&
+		one.offset === two.offset &&
+		one.length === two.length &&
+		one.sha256 === two.sha256
+	)
+}
+function immutableCursor(value: PalActivityCursor): PalActivityCursor {
+	return Object.freeze({
+		...value,
+		root: Object.freeze({ ...value.root }),
+		after: Object.freeze({ ...value.after }),
+	})
+}
+
+/** Bounded original-byte reads, with current host consent and exact Pal-root admission. */
+export function createPalActivitySource(options: PalActivitySourceOptions): PalActivitySource {
+	const scope = Object.freeze(scopeSchema.parse(options.scope))
+	const { pals, authorize, openJournal } = options
+	if (typeof authorize !== 'function' || typeof openJournal !== 'function')
+		throw new TypeError('Pal activity requires explicit authorization and original-journal ports.')
+	return {
+		scope,
+		async read(input: PalActivityReadOptions) {
+			const { signal } = input
+			const maxRecords = positive.max(256).parse(input.maxRecords)
+			const maxReadBytes = positive.max(16 * 1024 * 1024).parse(input.maxReadBytes)
+			const supplied = input.cursor ? cursorSchema.parse(input.cursor) : undefined
+			signal.throwIfAborted()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			const definition = pals.getRevision(scope.palId, scope.profileRevision)
+			if (definition.id !== scope.palId || definition.revision !== scope.profileRevision)
+				throw new PalActivityIntegrityError()
+			const workspace = definition.workspace
+			const scopeHash = createHash('sha256')
+				.update(
+					JSON.stringify([
+						'pal-activity/1',
+						scope.tenantId,
+						scope.projectId,
+						scope.palId,
+						scope.profileRevision,
+						scope.sessionId,
+						workspace,
+					]),
+				)
+				.digest('hex')
+			if (supplied && supplied.scopeHash !== scopeHash) throw new PalActivityIntegrityError()
+			const journal = await openJournal(scope, signal)
+			signal.throwIfAborted()
+			if (journal.log.sessionId !== scope.sessionId) throw new PalActivityIntegrityError()
+			const bytes = journal.bytes
+			const size = await bytes.size()
+			signal.throwIfAborted()
+			if (!Number.isSafeInteger(size) || size < 1) throw new PalActivityIntegrityError()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			let readBytes = 0
+			const read = async (offset: number, length: number): Promise<Uint8Array> => {
+				signal.throwIfAborted()
+				if (length > maxReadBytes - readBytes) throw new PalActivityReadLimitError()
+				readBytes += length
+				const raw = await bytes.read(offset, length)
+				signal.throwIfAborted()
+				if (raw.byteLength !== length) throw new PalActivityIntegrityError()
+				return Uint8Array.from(raw)
+			}
+			const lineAt = async (offset: number): Promise<Uint8Array> => {
+				const parts: Uint8Array[] = []
+				let length = 0
+				while (offset + length < size) {
+					const available = maxReadBytes - readBytes
+					if (available === 0) throw new PalActivityReadLimitError()
+					const chunk = await read(
+						offset + length,
+						Math.min(1024, available, size - offset - length),
+					)
+					const newline = chunk.indexOf(10)
+					const part = newline < 0 ? chunk : chunk.subarray(0, newline + 1)
+					parts.push(part)
+					length += part.byteLength
+					if (length > SESSION_RECORD_MAX_BYTES) throw new PalActivityReadLimitError()
+					if (newline >= 0) return Buffer.concat(parts)
+				}
+				throw new PalActivityIntegrityError()
+			}
+			const first = await lineAt(0)
+			let root: SessionLogEntry
+			try {
+				root = new SessionLogChain({ head: null, sessionId: scope.sessionId }).accept(first, 0)
+			} catch {
+				throw new PalActivityIntegrityError()
+			}
+			const owner = root.record
+			if (
+				owner.type !== 'session_started' ||
+				owner.parent ||
+				owner.forkedFrom ||
+				owner.tenantId !== scope.tenantId ||
+				owner.projectId !== scope.projectId ||
+				owner.cwd !== workspace ||
+				owner.origin?.protocol !== 'desktop' ||
+				owner.origin.externalSessionId !==
+					JSON.stringify(['namzu-pal', scope.palId, scope.profileRevision, scope.sessionId])
+			)
+				throw new PalActivityIntegrityError()
+			if ((await read(size - 1, 1))[0] !== 10) throw new PalActivityIntegrityError()
+			let after = root.pointer
+			let generation = root.record.gen
+			if (supplied) {
+				const anchorEnd = supplied.after.offset + supplied.after.length
+				if (
+					!samePointer(root.pointer, supplied.root) ||
+					!Number.isSafeInteger(anchorEnd) ||
+					anchorEnd > size ||
+					supplied.after.seq < 1 ||
+					(supplied.after.seq > 1 && supplied.after.offset < root.pointer.length)
+				)
+					throw new PalActivityIntegrityError()
+				let anchor: ReturnType<typeof parseSessionLogLine>
+				try {
+					anchor = parseSessionLogLine(await read(supplied.after.offset, supplied.after.length))
+				} catch (error) {
+					signal.throwIfAborted()
+					if (error instanceof PalActivityReadLimitError) throw error
+					throw new PalActivityIntegrityError()
+				}
+				if (
+					anchor.sha256 !== supplied.after.sha256 ||
+					anchor.record.sessionId !== scope.sessionId ||
+					anchor.record.seq !== supplied.after.seq ||
+					anchor.record.gen !== supplied.generation ||
+					(supplied.after.seq === 1 && !samePointer(supplied.after, root.pointer))
+				)
+					throw new PalActivityIntegrityError()
+				after = supplied.after
+				generation = anchor.record.gen
+			}
+			const chain = new SessionLogChain({
+				head: after,
+				sessionId: scope.sessionId,
+				gen: generation,
+			})
+			const facts: PalActivityFact[] = []
+			let scannedRecords = 0
+			while (chain.end < size && scannedRecords < maxRecords) {
+				const raw = await lineAt(chain.end)
+				let entry: SessionLogEntry
+				let fact: PalActivityFact | null
+				try {
+					entry = chain.accept(raw, chain.end)
+					fact = projectPalActivity(entry, scopeHash)
+				} catch {
+					throw new PalActivityIntegrityError()
+				}
+				scannedRecords++
+				if (fact) facts.push(fact)
+				after = entry.pointer
+				generation = entry.record.gen
+			}
+			if ((await bytes.size()) < size) throw new PalActivityIntegrityError()
+			signal.throwIfAborted()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			return Object.freeze({
+				scope,
+				facts: Object.freeze(facts),
+				cursor: immutableCursor({ v: 1, scopeHash, root: root.pointer, after, generation }),
+				complete: chain.end === size,
+				scannedRecords,
+				readBytes,
+			})
+		},
+	}
+}