@namzu/sdk 38.1.0 → 39.0.0

package/dist/manager/resident/store.d.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import type { TenantId } from '../../types/ids/index.js';
+export declare const residentDecisionSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"wait">;
+    summary: z.ZodString;
+    wakeAt: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    kind: "wait";
+    summary: string;
+    wakeAt: number | null;
+}, {
+    kind: "wait";
+    summary: string;
+    wakeAt: number | null;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"complete">;
+    summary: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "complete";
+    summary: string;
+}, {
+    kind: "complete";
+    summary: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"blocked">;
+    summary: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "blocked";
+    summary: string;
+}, {
+    kind: "blocked";
+    summary: string;
+}>]>;
+/** @experimental One bounded step's durable disposition; silence is not completion. */
+export type ResidentDecision = z.infer<typeof residentDecisionSchema>;
+export declare const residentStateSchema: z.ZodEffects<z.ZodObject<{
+    tenantId: z.ZodString;
+    agentKey: z.ZodString;
+    pursuitId: z.ZodOptional<z.ZodString>;
+    identity: z.ZodString;
+    objective: z.ZodString;
+    revision: z.ZodNumber;
+    stepsAdmitted: z.ZodNumber;
+    phase: z.ZodEnum<["waiting", "running", "complete", "blocked"]>;
+    wakeAt: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodString;
+    /** Accepted wake inputs, in commit order, retained until this step settles. */
+    wakeEvidence: z.ZodOptional<z.ZodReadonly<z.ZodEffects<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        reason: z.ZodString;
+        receivedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        reason: string;
+        receivedAt: number;
+    }, {
+        reason: string;
+        receivedAt: number;
+    }>>, "many">, Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[], Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[]>>>;
+    summary: z.ZodNullable<z.ZodString>;
+    claimId: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    summary: string | null;
+    phase: "running" | "complete" | "blocked" | "waiting";
+    identity: string;
+    reason: string;
+    revision: number;
+    tenantId: string;
+    objective: string;
+    wakeAt: number | null;
+    agentKey: string;
+    stepsAdmitted: number;
+    claimId: string | null;
+    pursuitId?: string | undefined;
+    wakeEvidence?: readonly Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[] | undefined;
+}, {
+    summary: string | null;
+    phase: "running" | "complete" | "blocked" | "waiting";
+    identity: string;
+    reason: string;
+    revision: number;
+    tenantId: string;
+    objective: string;
+    wakeAt: number | null;
+    agentKey: string;
+    stepsAdmitted: number;
+    claimId: string | null;
+    pursuitId?: string | undefined;
+    wakeEvidence?: readonly Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[] | undefined;
+}>, {
+    summary: string | null;
+    phase: "running" | "complete" | "blocked" | "waiting";
+    identity: string;
+    reason: string;
+    revision: number;
+    tenantId: string;
+    objective: string;
+    wakeAt: number | null;
+    agentKey: string;
+    stepsAdmitted: number;
+    claimId: string | null;
+    pursuitId?: string | undefined;
+    wakeEvidence?: readonly Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[] | undefined;
+}, {
+    summary: string | null;
+    phase: "running" | "complete" | "blocked" | "waiting";
+    identity: string;
+    reason: string;
+    revision: number;
+    tenantId: string;
+    objective: string;
+    wakeAt: number | null;
+    agentKey: string;
+    stepsAdmitted: number;
+    claimId: string | null;
+    pursuitId?: string | undefined;
+    wakeEvidence?: readonly Readonly<{
+        reason: string;
+        receivedAt: number;
+    }>[] | undefined;
+}>;
+/** @experimental Persisted identity and one pursuit, independent of a conversation. */
+export type ResidentState = Readonly<z.infer<typeof residentStateSchema>>;
+/** Bounded addressing for local resident state. Stored scope is still validated. */
+export declare function residentKeySegment(key: string): string;
+/** @experimental Minimal atomic contract needed to execute an existing pursuit. */
+export type ResidentExecutionStore = Pick<ResidentStore, 'read' | 'claim' | 'settle'>;
+/** @experimental Backends must atomically compare revisions and publish admission before work. */
+export interface ResidentStore {
+    read(): Promise<ResidentState | null>;
+    create(identity: string, objective: string): Promise<ResidentState>;
+    claim(expected: ResidentState, now: number): Promise<ResidentState>;
+    settle(expected: ResidentState, decision: ResidentDecision, now: number): Promise<ResidentState>;
+    wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState>;
+}
+/** A competing owner advanced this resident's immutable revision. */
+export declare class ResidentConflictError extends Error {
+    constructor();
+}
+/**
+ * @experimental Local-filesystem state for one tenant/agent key and one pursuit.
+ * A running claim never expires automatically: a crashed step may have effects.
+ * Uses exclusive immutable revision publication, not a read/rename lock.
+ */
+export declare class DiskResidentStore implements ResidentStore {
+    private readonly records;
+    private readonly location;
+    private readonly tenantId;
+    private readonly agentKey;
+    constructor(root: string, scope: {
+        tenantId: TenantId;
+        agentKey: string;
+    });
+    private checked;
+    read(): Promise<ResidentState | null>;
+    create(identity: string, objective: string): Promise<ResidentState>;
+    private change;
+    /** Persist admission before invoking a model, tool or developer callback. */
+    claim(expected: ResidentState, now: number): Promise<ResidentState>;
+    /** Only the exact admitted revision may settle; late owners cannot overwrite recovery. */
+    settle(expected: ResidentState, decision: ResidentDecision, now: number): Promise<ResidentState>;
+    /** Host-supplied new evidence can wake a waiting pursuit; terminal work stays terminal. */
+    wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState>;
+}
+/** Internal transitions shared by single-pursuit and whole-agent admission. */
+export declare function claimResidentState(state: ResidentState, now: number): ResidentState;
+export declare function settleResidentState(state: ResidentState, decision: ResidentDecision, now: number): ResidentState;
+export declare function wakeResidentState(state: ResidentState, reason: string, now: number): ResidentState;
+//# sourceMappingURL=store.d.ts.map

package/dist/manager/resident/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/store.ts"],"names":[],"mappings":"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"}

package/dist/manager/resident/store.js

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { DiskRevisionRecordStore, revisionFileSegment, } from '../../store/kv/revision-record-store.js';
+import { defineSchema } from '../../store/schema.js';
+import { asTenantId } from '../../utils/id.js';
+const text = z.string().trim().min(1).max(8_000);
+const time = z.number().int().nonnegative().safe();
+const MAX_WAKE_EVIDENCE_CHARS = 16_000;
+const wakeEvidence = z
+    .array(z.object({ reason: text, receivedAt: time }).readonly())
+    .min(1)
+    .max(16, 'Resident has 16 pending wake inputs; process them before adding more.')
+    .refine((entries) => entries.reduce((total, entry) => total + entry.reason.length, 0) <= MAX_WAKE_EVIDENCE_CHARS, 'Resident wake evidence exceeds 16000 characters; process pending evidence before adding more.')
+    .readonly();
+export const residentDecisionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('wait'), summary: text, wakeAt: time.nullable() }),
+    z.object({ kind: z.literal('complete'), summary: text }),
+    z.object({ kind: z.literal('blocked'), summary: text }),
+]);
+export const residentStateSchema = z
+    .object({
+    tenantId: z.string().uuid(),
+    agentKey: z.string().min(1).max(200),
+    pursuitId: z.string().uuid().optional(),
+    identity: text,
+    objective: text,
+    revision: z.number().int().positive().safe(),
+    stepsAdmitted: time,
+    phase: z.enum(['waiting', 'running', 'complete', 'blocked']),
+    wakeAt: time.nullable(),
+    reason: text,
+    /** Accepted wake inputs, in commit order, retained until this step settles. */
+    wakeEvidence: wakeEvidence.optional(),
+    summary: text.nullable(),
+    claimId: z.string().uuid().nullable(),
+})
+    .superRefine((state, context) => {
+    if ((state.phase === 'running') !== (state.claimId !== null)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Running state requires a claim.',
+        });
+    }
+    if (state.phase !== 'waiting' && state.wakeAt !== null) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Only waiting state may have a wake time.',
+        });
+    }
+    if (state.wakeEvidence && state.phase !== 'waiting' && state.phase !== 'running') {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Only waiting or unresolved running work may retain wake evidence.',
+        });
+    }
+});
+/** Bounded addressing for local resident state. Stored scope is still validated. */
+export function residentKeySegment(key) {
+    const encoded = revisionFileSegment(key);
+    return encoded.length <= 255
+        ? encoded
+        : `~sha256-${createHash('sha256').update(encoded).digest('hex')}`;
+}
+/** A competing owner advanced this resident's immutable revision. */
+export class ResidentConflictError extends Error {
+    constructor() {
+        super('Resident state changed; read the current state before retrying.');
+        this.name = 'ResidentConflictError';
+    }
+}
+/**
+ * @experimental Local-filesystem state for one tenant/agent key and one pursuit.
+ * A running claim never expires automatically: a crashed step may have effects.
+ * Uses exclusive immutable revision publication, not a read/rename lock.
+ */
+export class DiskResidentStore {
+    records = new DiskRevisionRecordStore(defineSchema({ kind: 'resident', current: 2, migrations: { 1: (record) => record } }), 'resident store', (record) => record.revision);
+    location;
+    tenantId;
+    agentKey;
+    constructor(root, scope) {
+        this.tenantId = asTenantId(scope.tenantId);
+        this.agentKey = z.string().min(1).max(200).parse(scope.agentKey);
+        const directory = join(root, this.tenantId, residentKeySegment(this.agentKey));
+        this.location = {
+            legacyPath: join(directory, 'state.json'),
+            revisionsDir: join(directory, 'revisions'),
+            publishLegacyProjection: false,
+        };
+    }
+    checked(record) {
+        const state = residentStateSchema.parse(record);
+        if (state.pursuitId !== undefined ||
+            state.tenantId !== this.tenantId ||
+            state.agentKey !== this.agentKey) {
+            throw new Error('Resident record does not match the bound tenant and agent.');
+        }
+        return Object.freeze(state);
+    }
+    async read() {
+        const state = await this.records.read(this.location);
+        return state === null ? null : this.checked(state);
+    }
+    async create(identity, objective) {
+        const initial = this.checked({
+            tenantId: this.tenantId,
+            agentKey: this.agentKey,
+            identity,
+            objective,
+            revision: 1,
+            stepsAdmitted: 0,
+            phase: 'waiting',
+            wakeAt: 0,
+            reason: 'Initial pursuit',
+            summary: null,
+            claimId: null,
+        });
+        return this.records.transact(this.location, (current) => {
+            if (current !== null)
+                throw new ResidentConflictError();
+            return { record: initial, result: initial };
+        });
+    }
+    async change(expected, mutate) {
+        this.checked(expected);
+        return this.records.transact(this.location, (record) => {
+            if (record === null)
+                throw new ResidentConflictError();
+            const current = this.checked(record);
+            if (current.revision !== expected.revision || current.claimId !== expected.claimId) {
+                throw new ResidentConflictError();
+            }
+            const next = this.checked({
+                ...mutate(current),
+                revision: current.revision + 1,
+            });
+            return { record: next, result: next };
+        });
+    }
+    /** Persist admission before invoking a model, tool or developer callback. */
+    async claim(expected, now) {
+        return this.change(expected, (state) => claimResidentState(state, now));
+    }
+    /** Only the exact admitted revision may settle; late owners cannot overwrite recovery. */
+    async settle(expected, decision, now) {
+        return this.change(expected, (state) => settleResidentState(state, decision, now));
+    }
+    /** Host-supplied new evidence can wake a waiting pursuit; terminal work stays terminal. */
+    async wake(expected, reason, now) {
+        return this.change(expected, (state) => wakeResidentState(state, reason, now));
+    }
+}
+/** Internal transitions shared by single-pursuit and whole-agent admission. */
+export function claimResidentState(state, now) {
+    time.parse(now);
+    if (state.phase !== 'waiting' || state.wakeAt === null || state.wakeAt > now)
+        throw new Error('Resident is not due.');
+    return {
+        ...state,
+        phase: 'running',
+        wakeAt: null,
+        claimId: randomUUID(),
+        stepsAdmitted: state.stepsAdmitted + 1,
+    };
+}
+export function settleResidentState(state, decision, now) {
+    time.parse(now);
+    const outcome = residentDecisionSchema.parse(decision);
+    if (outcome.kind === 'wait' && outcome.wakeAt !== null && outcome.wakeAt <= now)
+        throw new Error('A scheduled continuation must be in the future.');
+    if (state.phase !== 'running')
+        throw new Error('Resident has no admitted step to settle.');
+    // Admission alone is not acknowledgment: an interrupted step retains every
+    // input. Only successful exact-claim settlement consumes the captured batch.
+    const { wakeEvidence: _consumed, ...settled } = state;
+    return {
+        ...settled,
+        phase: outcome.kind === 'wait' ? 'waiting' : outcome.kind,
+        wakeAt: outcome.kind === 'wait' ? outcome.wakeAt : null,
+        summary: outcome.summary,
+        reason: 'Scheduled continuation',
+        claimId: null,
+    };
+}
+export function wakeResidentState(state, reason, now) {
+    time.parse(now);
+    const evidence = text.parse(reason);
+    if (state.phase !== 'waiting')
+        throw new Error('Only a waiting resident can be woken.');
+    // Never evict an accepted input to admit another. Backpressure leaves both
+    // the durable state and its revision untouched, so the sender can retry later.
+    const pending = wakeEvidence.parse([
+        ...(state.wakeEvidence ?? []),
+        { reason: evidence, receivedAt: now },
+    ]);
+    return { ...state, wakeAt: now, reason: evidence, wakeEvidence: pending };
+}
+//# sourceMappingURL=store.js.map

package/dist/manager/resident/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/manager/resident/store.ts"],"names":[],"mappings":"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"}

package/dist/manager/resident/tool-evidence.d.ts

@@ -0,0 +1,71 @@
+import type { RunEvidenceReadOptions, RunEvidenceReadResult, RunEvidenceSearchResult, RunEvidenceSource } from '../../store/evidence/types.js';
+import type { ResidentHistoryMatch, ResidentHistoryScope, ResidentHistorySource } from './history.js';
+/** @experimental Host authority for one pursuit, project and admission boundary. */
+export interface ResidentToolEvidenceScope extends ResidentHistoryScope {
+    readonly projectId: string;
+}
+/** @experimental Identity of an agenda-verified settlement, not a fabricated transcript. */
+export type ResidentSettledInvocation = Pick<ResidentHistoryMatch, 'revision' | 'claimId' | 'step' | 'kind'>;
+/** @experimental Settlement is checked before the host resolves the attempt's invocation. */
+export interface ResidentToolEvidenceOptions {
+    readonly history: ResidentHistorySource;
+    readonly projectId: string;
+    /** Host-enforced upper bound for resolveRun's document reads, charged in full.
+     * Required only when an operation supplies maxReadBytes. Zero asserts no
+     * document reads. This is a declared bound, not a measured receipt.
+     */
+    readonly resolutionReadBytes?: number;
+    readonly resolveRun: (settled: ResidentSettledInvocation, signal?: AbortSignal) => Promise<RunEvidenceSource>;
+}
+/** @experimental An optional shared ceiling covers history, resolution and run evidence. */
+export interface ResidentToolEvidenceSearchOptions {
+    readonly query?: string;
+    /** Token discovery: 1–16 terms, matched case-insensitively. Combined query/filter JSON ≤512 UTF-8 bytes. */
+    readonly terms?: readonly string[];
+    /** Omit successful retrieval copies before they consume candidate slots. */
+    readonly excludeSuccessfulTools?: readonly string[];
+    /** Omit query/terms/filter to continue the exact captured search. */
+    readonly cursor?: string;
+    /** With a token cursor, continue using a strict subset of its terms. Requires
+     * supportsTermRefinement. Scope, exclusions and the original cursor stay intact.
+     */
+    readonly refineTerms?: readonly string[];
+    readonly maxReadBytes?: number;
+}
+/** @experimental Tool records from at most one settled invocation per bounded search page. */
+export interface ResidentToolEvidenceSearchResult {
+    readonly scope: ResidentToolEvidenceScope;
+    readonly revision: number | null;
+    readonly claimId: string | null;
+    readonly evidence: RunEvidenceSearchResult | null;
+    readonly nextCursor: string | null;
+    readonly incomplete: boolean;
+    readonly unavailableRevisions: readonly number[];
+    readonly historyBytes: number;
+    /** Present for bounded calls: history + declared resolution + run reads.
+     * Failed source reads without a receipt conservatively consume the remainder.
+     */
+    readonly chargedBytes?: number;
+}
+/** @experimental The revision is authorized anew on every read, including after restart. */
+export interface ResidentToolEvidenceReadOptions extends Omit<RunEvidenceReadOptions, 'maxReadBytes'> {
+    readonly revision: number;
+    /** Shared operation ceiling, at most 8 MiB; reserves at least 1 MiB for run reads. */
+    readonly maxReadBytes?: number;
+}
+/** @experimental Exact invocation text plus the settled claim that authorized access. */
+export interface ResidentToolEvidenceReadResult extends RunEvidenceReadResult {
+    readonly revision: number;
+    readonly claimId: string;
+    readonly chargedBytes?: number;
+}
+/** @experimental A host must bind tool access to the executing run, not just this source. */
+export interface ResidentToolEvidenceSource {
+    readonly scope: ResidentToolEvidenceScope;
+    readonly supportsTermRefinement?: boolean;
+    search(options?: ResidentToolEvidenceSearchOptions, signal?: AbortSignal): Promise<ResidentToolEvidenceSearchResult>;
+    read(options: ResidentToolEvidenceReadOptions, signal?: AbortSignal): Promise<ResidentToolEvidenceReadResult>;
+}
+/** @experimental Reuses the immutable agenda boundary; it never enumerates arbitrary sessions. */
+export declare function createResidentToolEvidenceSource(options: ResidentToolEvidenceOptions): ResidentToolEvidenceSource;
+//# sourceMappingURL=tool-evidence.d.ts.map

package/dist/manager/resident/tool-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-evidence.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/tool-evidence.ts"],"names":[],"mappings":"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"}