@namzu/sdk 38.2.1 → 40.0.0

package/src/manager/resident/activity.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod'
+import type { ResidentAgendaState } from './agenda.js'
+import { ResidentHistoryPageLimit, type ResidentHistoryReadBudget } from './history-disk.js'
+
+/** @experimental An immutable upper boundary; new work requires a new source. */
+export interface ResidentActivityScope {
+	readonly tenantId: string
+	readonly agentKey: string
+	readonly throughRevision: number
+}
+
+/** @experimental Admission is authority to inspect an attempt, not proof that it executed. */
+export interface ResidentAdmission {
+	readonly revision: number
+	readonly pursuitRevision: number
+	readonly pursuitId: string
+	readonly claimId: string
+	readonly step: number
+	readonly objective: string
+}
+
+/** @experimental Settlement is an agenda decision, not proof of verification or delivery. */
+export interface ResidentSettlement {
+	readonly revision: number
+	readonly pursuitId: string
+	readonly claimId: string
+	readonly outcome: 'wait' | 'complete' | 'blocked'
+}
+
+/** @experimental Forward pages; cursor is the next revision to inspect, initially 1. */
+export interface ResidentActivityOptions {
+	readonly cursor?: number
+	readonly maxRevisions?: number
+	readonly maxReadBytes?: number
+}
+
+/** @experimental Gaps stay explicit; counts cover only the scanned revision range. */
+export interface ResidentActivityPage {
+	readonly scope: ResidentActivityScope
+	readonly fromRevision: number
+	readonly throughRevision: number
+	readonly nextCursor: number | null
+	readonly scannedBytes: number
+	readonly unavailableRevisions: readonly number[]
+	readonly admissions: readonly ResidentAdmission[]
+	readonly settlements: readonly ResidentSettlement[]
+	readonly archivedPursuits: readonly string[]
+}
+
+/** @experimental A backend must enforce scope, cancellation and read bounds. */
+export interface ResidentActivitySource {
+	readonly scope: ResidentActivityScope
+	read(options?: ResidentActivityOptions, signal?: AbortSignal): Promise<ResidentActivityPage>
+}
+
+/** Internal adapter for the immutable disk agenda. */
+export function createResidentActivitySource(
+	scopeInput: ResidentActivityScope,
+	load: (revision: number, budget: ResidentHistoryReadBudget) => Promise<ResidentAgendaState>,
+): ResidentActivitySource {
+	const scope = Object.freeze(
+		z
+			.object({
+				tenantId: z.string().uuid(),
+				agentKey: z.string().min(1).max(200),
+				throughRevision: z.number().int().positive().safe(),
+			})
+			.parse(scopeInput),
+	)
+	return {
+		scope,
+		async read(options: ResidentActivityOptions = {}, signal?: AbortSignal) {
+			const from = z
+				.number()
+				.int()
+				.positive()
+				.max(scope.throughRevision)
+				.parse(options.cursor ?? 1)
+			const count = z
+				.number()
+				.int()
+				.positive()
+				.max(32)
+				.parse(options.maxRevisions ?? 32)
+			const budget: ResidentHistoryReadBudget = {
+				remaining: z
+					.number()
+					.int()
+					.positive()
+					.max(8 * 1024 * 1024)
+					.parse(options.maxReadBytes ?? 8 * 1024 * 1024),
+				bytesRead: 0,
+				signal,
+			}
+			const unavailable = new Set<number>()
+			const read = async (revision: number) => {
+				signal?.throwIfAborted()
+				try {
+					const state = await load(revision, budget)
+					if (
+						state.tenantId !== scope.tenantId ||
+						state.agentKey !== scope.agentKey ||
+						state.revision !== revision
+					)
+						throw new Error('Resident activity scope mismatch.')
+					return state
+				} catch (error) {
+					signal?.throwIfAborted()
+					if (error instanceof ResidentHistoryPageLimit) throw error
+					unavailable.add(revision)
+					return null
+				}
+			}
+			const admissions: ResidentAdmission[] = []
+			const settlements: ResidentSettlement[] = []
+			const archivedPursuits: string[] = []
+			let through = from - 1
+			try {
+				let before = from > 1 ? await read(from - 1) : null
+				for (
+					let revision = from;
+					revision <= Math.min(scope.throughRevision, from + count - 1);
+					revision++
+				) {
+					const after = await read(revision)
+					if (before && after) {
+						for (const pursuit of after.pursuits) {
+							const previous = before.pursuits.find((p) => p.id === pursuit.id)?.state
+							const current = pursuit.state
+							if (!previous) continue
+							if (
+								current.revision === previous.revision + 1 &&
+								previous.phase !== 'running' &&
+								current.phase === 'running' &&
+								current.claimId &&
+								current.stepsAdmitted === previous.stepsAdmitted + 1
+							) {
+								admissions.push({
+									revision,
+									pursuitRevision: current.revision,
+									pursuitId: pursuit.id,
+									claimId: current.claimId,
+									step: current.stepsAdmitted,
+									objective: current.objective,
+								})
+							}
+							if (
+								current.revision === previous.revision + 1 &&
+								previous.phase === 'running' &&
+								previous.claimId &&
+								current.phase !== 'running' &&
+								current.claimId === null &&
+								current.stepsAdmitted === previous.stepsAdmitted
+							) {
+								settlements.push({
+									revision,
+									pursuitId: pursuit.id,
+									claimId: previous.claimId,
+									outcome: current.phase === 'waiting' ? 'wait' : current.phase,
+								})
+							}
+						}
+						if (after.archiveHead === revision)
+							for (const pursuit of before.pursuits)
+								if (!after.pursuits.some((p) => p.id === pursuit.id))
+									archivedPursuits.push(pursuit.id)
+					}
+					through = revision
+					before = after
+				}
+			} catch (error) {
+				if (!(error instanceof ResidentHistoryPageLimit)) throw error
+			}
+			return {
+				scope,
+				fromRevision: from,
+				throughRevision: through,
+				nextCursor: through < scope.throughRevision ? through + 1 : null,
+				scannedBytes: budget.bytesRead,
+				unavailableRevisions: [...unavailable],
+				admissions,
+				settlements,
+				archivedPursuits,
+			}
+		},
+	}
+}

package/src/manager/resident/agenda.ts

@@ -1,10 +1,10 @@
 import { randomUUID } from 'node:crypto'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import { isDeepStrictEqual } from 'node:util'
 import { z } from 'zod'
 import { DiskRecordStore } from '../../store/kv/record-store.js'
 import { DiskRevisionRecordStore } from '../../store/kv/revision-record-store.js'
-import { defineSchema } from '../../store/schema.js'
+import { defineSchema, migrate } from '../../store/schema.js'
 import type { TenantId } from '../../types/ids/index.js'
 import { asTenantId } from '../../utils/id.js'
 import {
@@ -20,6 +20,9 @@ import {
 	wakeResidentState,
 } from './store.js'
 
+import { type ResidentActivitySource, createResidentActivitySource } from './activity.js'
+import { readResidentHistoryRecord } from './history-disk.js'
+import { type ResidentHistorySource, createResidentHistorySource } from './history.js'
 import {
 	type ResidentFeedback,
 	type ResidentObservation,
@@ -186,12 +189,13 @@ export interface ResidentArchiveListOptions {
 
 const agendaRecordSchema = defineSchema({
 	kind: 'resident-agenda',
-	current: 5,
+	current: 6,
 	migrations: {
 		1: (record) => record,
 		2: (record) => record,
 		3: (record) => record,
 		4: (record) => record,
+		5: (record) => record,
 	},
 })
 
@@ -254,10 +258,12 @@ export class DiskResidentAgenda implements ResidentAgendaStore {
 		'resident agenda',
 		(record) => record.revision,
 	)
-	private readonly history = new DiskRecordStore<ResidentAgendaState>(agendaRecordSchema)
+	private readonly historyRecords = new DiskRecordStore<ResidentAgendaState>(agendaRecordSchema)
 	private readonly location
 	private readonly tenantId: TenantId
 	private readonly agentKey: string
+	private readonly historyRoot: string
+	private readonly historyRevisions: string
 
 	constructor(root: string, scope: { tenantId: TenantId; agentKey: string }) {
 		this.tenantId = asTenantId(scope.tenantId)
@@ -268,6 +274,8 @@ export class DiskResidentAgenda implements ResidentAgendaStore {
 			revisionsDir: join(directory, 'revisions'),
 			publishLegacyProjection: false,
 		}
+		this.historyRoot = resolve(root)
+		this.historyRevisions = resolve(this.location.revisionsDir)
 	}
 
 	private checked(record: ResidentAgendaState): ResidentAgendaState {
@@ -301,13 +309,59 @@ export class DiskResidentAgenda implements ResidentAgendaStore {
 	/** Read one authoritative immutable commit, never the compatibility projection. */
 	async readRevision(revision: number): Promise<ResidentAgendaState | null> {
 		z.number().int().positive().safe().parse(revision)
-		const record = await this.history.read(join(this.location.revisionsDir, `${revision}.json`))
+		const record = await this.historyRecords.read(
+			join(this.location.revisionsDir, `${revision}.json`),
+		)
 		if (record === null) return null
 		const state = this.checked(record)
 		if (state.revision !== revision) throw new Error('Agenda revision filename and body disagree.')
 		return state
 	}
 
+	/**
+	 * Bind bounded historical reads to this pursuit and a host-selected upper
+	 * agenda revision (normally ResidentStepContext.agendaRevision). No I/O or
+	 * inference occurs until search/read; the boundary never advances itself.
+	 */
+	history(pursuit: ResidentState, throughRevision: number): ResidentHistorySource {
+		const state = residentStateSchema.parse(pursuit)
+		if (state.tenantId !== this.tenantId || state.agentKey !== this.agentKey || !state.pursuitId)
+			throw new Error('History requires a pursuit belonging to this resident agenda.')
+		z.number().int().positive().safe().parse(throughRevision)
+		return createResidentHistorySource(
+			{
+				tenantId: this.tenantId,
+				agentKey: this.agentKey,
+				pursuitId: state.pursuitId,
+				throughRevision,
+			},
+			state,
+			async (revision, budget) => {
+				const raw = await readResidentHistoryRecord(
+					this.historyRoot,
+					join(this.historyRevisions, `${revision}.json`),
+					budget,
+				)
+				return this.checked(migrate<ResidentAgendaState>(agendaRecordSchema, raw))
+			},
+		)
+	}
+
+	/** @experimental Bounded admission/settlement history, including archived pursuits. */
+	activity(throughRevision: number): ResidentActivitySource {
+		return createResidentActivitySource(
+			{ tenantId: this.tenantId, agentKey: this.agentKey, throughRevision },
+			async (revision, budget) => {
+				const raw = await readResidentHistoryRecord(
+					this.historyRoot,
+					join(this.historyRevisions, `${revision}.json`),
+					budget,
+				)
+				return this.checked(migrate<ResidentAgendaState>(agendaRecordSchema, raw))
+			},
+		)
+	}
+
 	private retire(state: ResidentAgendaState, input: ResidentArchiveRequest): ResidentAgendaState {
 		const request = archiveRequestSchema.parse(input)
 		const pursuits = new Set(request.pursuitIds)

package/src/manager/resident/consumption.ts

@@ -0,0 +1,311 @@
+import { z } from 'zod'
+import type {
+	ResidentActivityScope,
+	ResidentActivitySource,
+	ResidentAdmission,
+	ResidentSettlement,
+} from './activity.js'
+
+const count = z.number().int().nonnegative().safe()
+const uuidKey = (id: string) => id.toLowerCase()
+const admissionSchema = z.object({
+	revision: count.positive(),
+	pursuitRevision: count.positive(),
+	pursuitId: z.string().uuid(),
+	claimId: z.string().uuid(),
+	step: count.positive(),
+	objective: z.string().min(1).max(8000),
+})
+const settlementSchema = z.object({
+	revision: count.positive(),
+	pursuitId: z.string().uuid(),
+	claimId: z.string().uuid(),
+	outcome: z.enum(['wait', 'complete', 'blocked']),
+})
+const receiptSchema = z
+	.object({
+		runId: z.string().uuid(),
+		/** Own usage includes retry and side-call spend; never add cache buckets again. */
+		ownTokens: count.nullable(),
+		treeTokens: count.nullable(),
+		ownCostUsd: z.number().nonnegative().finite().nullable(),
+		unpricedOwnTokens: count.nullable(),
+		usageFinal: z.boolean(),
+		cleanup: z.enum(['confirmed', 'unconfirmed', 'unknown']),
+		verification: z.enum(['recorded', 'unconfigured', 'unconfirmed']),
+	})
+	.superRefine((receipt, ctx) => {
+		if (
+			receipt.ownTokens !== null &&
+			receipt.treeTokens !== null &&
+			receipt.treeTokens < receipt.ownTokens
+		)
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Tree usage is below own usage.' })
+		if (
+			receipt.ownTokens !== null &&
+			receipt.unpricedOwnTokens !== null &&
+			receipt.unpricedOwnTokens > receipt.ownTokens
+		)
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Unpriced usage exceeds own usage.' })
+	})
+
+/** @experimental Host-authenticated cumulative root receipt. Cost covers this root only. */
+export type ResidentConsumptionReceipt = z.infer<typeof receiptSchema>
+
+/** @experimental A host resolves only authoritative admitted claims and bounds each read. */
+export interface ResidentConsumptionResolver {
+	/** Worst-case bytes read per resolution; reserved before calling the adapter. */
+	readonly maxReadBytes: number
+	resolve(
+		admission: ResidentAdmission,
+		signal?: AbortSignal,
+	): Promise<ResidentConsumptionReceipt | null>
+}
+
+/** @experimental Bounds the entire inspection, not just each page. No inference or writes. */
+export interface ResidentConsumptionOptions {
+	readonly cursor?: number
+	readonly maxRevisions?: number
+	readonly maxHistoryBytes?: number
+	readonly maxReceiptBytes?: number
+}
+
+/** @experimental Missing and deferred receipts never establish zero usage. */
+export interface ResidentConsumptionAttempt extends ResidentAdmission {
+	readonly settlement: ResidentSettlement | null
+	readonly receipt: ResidentConsumptionReceipt | null
+	readonly receiptStatus: 'available' | 'missing' | 'invalid' | 'deferred' | 'duplicate-run'
+}
+
+/** @experimental An evidence projection, not a bill or an enforced spending cap. */
+export interface ResidentConsumptionReport {
+	readonly scope: ResidentActivityScope
+	readonly fromRevision: number
+	readonly throughRevision: number
+	readonly nextCursor: number | null
+	readonly historyComplete: boolean
+	readonly unavailableRevisions: readonly number[]
+	readonly historyBytes: number
+	readonly receiptBytesReserved: number
+	readonly archivedPursuits: readonly string[]
+	readonly attempts: readonly ResidentConsumptionAttempt[]
+	readonly recorded: {
+		readonly ownTokens: number
+		readonly treeTokens: number
+		readonly ownCostUsd: number
+		readonly unpricedOwnTokens: number
+	}
+	readonly unknown: {
+		readonly ownUsageAttempts: number
+		readonly treeUsageAttempts: number
+		readonly ownPriceAttempts: number
+	}
+	/** Requires complete history and final receipts; says nothing about external billing. */
+	readonly usageComplete: boolean
+}
+
+/**
+ * @experimental Inspect cumulative root receipts once per admitted claim. Historical
+ * archive/reconcile events never erase consumption. Tree tokens are a separate total:
+ * adding them to own tokens would count the root twice. Descendant prices are unknown.
+ */
+export async function inspectResidentConsumption(
+	source: ResidentActivitySource,
+	resolver: ResidentConsumptionResolver,
+	options: ResidentConsumptionOptions = {},
+	signal?: AbortSignal,
+): Promise<ResidentConsumptionReport> {
+	const scope = z
+		.object({
+			tenantId: z.string().uuid(),
+			agentKey: z.string().min(1).max(200),
+			throughRevision: count.positive(),
+		})
+		.parse(source.scope)
+	const from = z
+		.number()
+		.int()
+		.positive()
+		.max(scope.throughRevision)
+		.parse(options.cursor ?? 1)
+	const maxRevisions = z
+		.number()
+		.int()
+		.positive()
+		.max(4096)
+		.parse(options.maxRevisions ?? 256)
+	const maxHistoryBytes = z
+		.number()
+		.int()
+		.positive()
+		.max(8 * 1024 * 1024)
+		.parse(options.maxHistoryBytes ?? 8 * 1024 * 1024)
+	const maxReceiptBytes = z
+		.number()
+		.int()
+		.nonnegative()
+		.max(64 * 1024 * 1024)
+		.parse(options.maxReceiptBytes ?? 16 * 1024 * 1024)
+	const resolutionBytes = z
+		.number()
+		.int()
+		.positive()
+		.max(1024 * 1024)
+		.parse(resolver.maxReadBytes)
+	const admissions = new Map<string, ResidentAdmission>()
+	const settlements = new Map<string, ResidentSettlement>()
+	const unavailable = new Set<number>()
+	const archived = new Map<string, string>()
+	let cursor: number | null = from
+	let through = from - 1
+	let historyBytes = 0
+	while (cursor !== null && through - from + 1 < maxRevisions && historyBytes < maxHistoryBytes) {
+		signal?.throwIfAborted()
+		const page = await source.read(
+			{
+				cursor,
+				maxRevisions: Math.min(32, maxRevisions - (through - from + 1)),
+				maxReadBytes: maxHistoryBytes - historyBytes,
+			},
+			signal,
+		)
+		signal?.throwIfAborted()
+		if (
+			page.scope.tenantId !== scope.tenantId ||
+			page.scope.agentKey !== scope.agentKey ||
+			page.scope.throughRevision !== scope.throughRevision ||
+			page.fromRevision !== cursor ||
+			!Number.isSafeInteger(page.throughRevision) ||
+			page.throughRevision < cursor - 1 ||
+			page.throughRevision > Math.min(scope.throughRevision, from + maxRevisions - 1) ||
+			!Number.isSafeInteger(page.scannedBytes) ||
+			page.scannedBytes < 0 ||
+			page.scannedBytes > maxHistoryBytes - historyBytes ||
+			page.nextCursor !==
+				(page.throughRevision === scope.throughRevision ? null : page.throughRevision + 1)
+		)
+			throw new Error('Invalid resident activity page.')
+		if (
+			page.admissions.length > 32 ||
+			page.settlements.length > 32 ||
+			page.archivedPursuits.length > 1024
+		)
+			throw new Error('Resident activity page exceeds event bounds.')
+		if (page.unavailableRevisions.length > 33) throw new Error('Invalid unavailable revision list.')
+		for (const revision of page.unavailableRevisions) {
+			count.positive().parse(revision)
+			if (revision < Math.max(1, cursor - 1) || revision > page.throughRevision)
+				throw new Error('Unavailable revision is outside the page.')
+			unavailable.add(revision)
+		}
+		for (const raw of page.admissions) {
+			const admission = Object.freeze(admissionSchema.parse(raw))
+			if (admission.revision < cursor || admission.revision > page.throughRevision)
+				throw new Error('Resident admission is outside its history page.')
+			if (admissions.has(uuidKey(admission.claimId)))
+				throw new Error('Duplicate resident admission.')
+			admissions.set(uuidKey(admission.claimId), admission)
+		}
+		for (const raw of page.settlements) {
+			const settlement = Object.freeze(settlementSchema.parse(raw))
+			if (settlement.revision < cursor || settlement.revision > page.throughRevision)
+				throw new Error('Resident settlement is outside its history page.')
+			if (settlements.has(uuidKey(settlement.claimId)))
+				throw new Error('Duplicate resident settlement.')
+			settlements.set(uuidKey(settlement.claimId), settlement)
+		}
+		for (const id of page.archivedPursuits) archived.set(uuidKey(z.string().uuid().parse(id)), id)
+		historyBytes += page.scannedBytes
+		through = page.throughRevision
+		if (page.nextCursor === cursor) break
+		cursor = page.nextCursor
+	}
+	const attempts: ResidentConsumptionAttempt[] = []
+	let receiptBytesReserved = 0
+	for (const admission of admissions.values()) {
+		signal?.throwIfAborted()
+		const settlement = settlements.get(uuidKey(admission.claimId))
+		if (
+			settlement &&
+			(uuidKey(settlement.pursuitId) !== uuidKey(admission.pursuitId) ||
+				settlement.revision <= admission.revision)
+		)
+			throw new Error('Resident settlement does not follow its admitted claim.')
+		let receipt: ResidentConsumptionReceipt | null = null
+		let receiptStatus: ResidentConsumptionAttempt['receiptStatus'] = 'deferred'
+		if (receiptBytesReserved + resolutionBytes <= maxReceiptBytes) {
+			receiptBytesReserved += resolutionBytes
+			try {
+				const value = await resolver.resolve(admission, signal)
+				signal?.throwIfAborted()
+				receipt = value === null ? null : receiptSchema.parse(value)
+				receiptStatus = receipt ? 'available' : 'missing'
+			} catch {
+				signal?.throwIfAborted()
+				receiptStatus = 'invalid'
+			}
+		}
+		attempts.push({
+			...admission,
+			settlement: settlements.get(uuidKey(admission.claimId)) ?? null,
+			receipt,
+			receiptStatus,
+		})
+	}
+	// A copied root receipt must not authenticate two claims. Exclude BOTH records.
+	const runCounts = new Map<string, number>()
+	for (const { receipt } of attempts)
+		if (receipt)
+			runCounts.set(uuidKey(receipt.runId), (runCounts.get(uuidKey(receipt.runId)) ?? 0) + 1)
+	const checked = attempts.map((attempt) =>
+		attempt.receipt && (runCounts.get(uuidKey(attempt.receipt.runId)) ?? 0) > 1
+			? { ...attempt, receipt: null, receiptStatus: 'duplicate-run' as const }
+			: attempt,
+	)
+	const recorded = { ownTokens: 0, treeTokens: 0, ownCostUsd: 0, unpricedOwnTokens: 0 }
+	const unknown = { ownUsageAttempts: 0, treeUsageAttempts: 0, ownPriceAttempts: 0 }
+	const add = (a: number, b: number) => {
+		const result = a + b
+		if (!Number.isSafeInteger(result))
+			throw new Error('Resident consumption exceeds the safe integer range.')
+		return result
+	}
+	let priceCorrection = 0
+	for (const { receipt } of checked) {
+		if (!receipt?.usageFinal || receipt.ownTokens === null) unknown.ownUsageAttempts++
+		if (!receipt?.usageFinal || receipt.treeTokens === null) unknown.treeUsageAttempts++
+		if (
+			!receipt?.usageFinal ||
+			receipt.ownCostUsd === null ||
+			receipt.unpricedOwnTokens === null ||
+			receipt.unpricedOwnTokens > 0
+		)
+			unknown.ownPriceAttempts++
+		recorded.ownTokens = add(recorded.ownTokens, receipt?.ownTokens ?? 0)
+		recorded.treeTokens = add(recorded.treeTokens, receipt?.treeTokens ?? 0)
+		recorded.unpricedOwnTokens = add(recorded.unpricedOwnTokens, receipt?.unpricedOwnTokens ?? 0)
+		// Compensated addition limits drift; provider prices are still estimates, not a bill.
+		const y = (receipt?.ownCostUsd ?? 0) - priceCorrection
+		const next = recorded.ownCostUsd + y
+		priceCorrection = next - recorded.ownCostUsd - y
+		if (!Number.isFinite(next)) throw new Error('Resident cost exceeds the supported range.')
+		recorded.ownCostUsd = next
+	}
+	const historyComplete = from === 1 && cursor === null && unavailable.size === 0
+	return {
+		scope,
+		fromRevision: from,
+		throughRevision: through,
+		nextCursor: cursor,
+		historyComplete,
+		unavailableRevisions: [...unavailable],
+		historyBytes,
+		receiptBytesReserved,
+		archivedPursuits: [...archived.values()],
+		attempts: checked,
+		recorded,
+		unknown,
+		usageComplete:
+			historyComplete && unknown.ownUsageAttempts === 0 && unknown.treeUsageAttempts === 0,
+	}
+}