@namzu/sdk 38.2.1 → 39.0.0

package/dist/manager/resident/evidence-recall.js

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+import { createScopedEvidenceRecallStep, evidenceRecallQueryTokens, refineEvidenceRecallTerms, } from '../../run/evidence-recall.js';
+import { evidenceTokenKey } from '../../utils/evidence-tokens.js';
+import { residentStateSchema } from './store.js';
+const ownerSchema = z.object({
+    tenantId: z.string().uuid(),
+    projectId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    runId: z.string().uuid(),
+});
+const historicalScopeSchema = ownerSchema.omit({ sessionId: true, runId: true }).extend({
+    agentKey: z.string().min(1).max(200),
+    pursuitId: z.string().uuid(),
+    throughRevision: z.number().int().positive().safe(),
+});
+// Sample both ends without merging or manufacturing a word at the cut. The
+// field still contributes at most 4000 characters; its omitted middle is not
+// inspected. Alternating ends also gives late corrections a term slot.
+function residentQueryWords(text) {
+    const words = text.length <= 4000
+        ? evidenceRecallQueryTokens(text)
+        : [
+            ...evidenceRecallQueryTokens(text
+                .slice(0, 2000)
+                .replace(/[\uD800-\uDBFF]$/u, '')
+                .replace(/[\p{L}\p{N}_]+$/u, '')),
+            ...evidenceRecallQueryTokens(text
+                .slice(-2000)
+                .replace(/^[\uDC00-\uDFFF]/u, '')
+                .replace(/^[\p{L}\p{N}_]+/u, '')),
+        ];
+    const result = [];
+    for (let left = 0, right = words.length - 1; left <= right; left++, right--) {
+        const first = words[left];
+        const last = words[right];
+        if (first)
+            result.push(first);
+        if (left !== right && last)
+            result.push(last);
+    }
+    return result;
+}
+/**
+ * Reuses the shared bounded ranking/rendering engine while retaining the
+ * pursuit's settlement authority. No arbitrary Session discovery, saved fact
+ * cache, inference, workspace reread or action replay is performed here.
+ */
+export function createResidentEvidenceRecallStep(options) {
+    const state = residentStateSchema.parse(options.state);
+    const owner = Object.freeze(ownerSchema.parse(options.scope));
+    const source = options.source;
+    const historicalScope = Object.freeze(historicalScopeSchema.parse(source.scope));
+    if (state.phase !== 'running' ||
+        !state.claimId ||
+        state.tenantId !== owner.tenantId ||
+        state.tenantId !== historicalScope.tenantId ||
+        owner.projectId !== historicalScope.projectId ||
+        state.agentKey !== historicalScope.agentKey ||
+        state.pursuitId !== historicalScope.pursuitId)
+        throw new Error('Resident recall requires one admitted pursuit and its authorized source.');
+    const exclusions = options.excludeSuccessfulTools
+        ? [...new Set(options.excludeSuccessfulTools)].sort()
+        : undefined;
+    if (exclusions &&
+        (exclusions.length > 16 ||
+            exclusions.some((name) => typeof name !== 'string' || !name.length || name.length > 256)))
+        throw new Error('Resident recall exclusions are invalid.');
+    if (Buffer.byteLength(JSON.stringify({
+        terms: ['x'],
+        ...(exclusions?.length ? { excludeSuccessfulTools: exclusions } : {}),
+    })) > 512)
+        throw new Error('Resident recall exclusions leave no bounded search room.');
+    const snapshot = JSON.stringify(historicalScope);
+    function assertSource() {
+        if (JSON.stringify(historicalScopeSchema.parse(source.scope)) !== snapshot)
+            throw new Error('Resident recall source changed ownership or admission boundary.');
+    }
+    // Round-robin categories keep a long objective or derived summary from
+    // monopolizing all search terms. Within wakes, newer accepted inputs start
+    // first; their original committed index is retained in query metadata.
+    const wakes = (state.wakeEvidence ?? [])
+        .map((wake, index) => ({
+        kind: 'accepted_wake',
+        index,
+        words: residentQueryWords(wake.reason),
+    }))
+        .reverse();
+    const wakeWords = [];
+    for (let word = 0; word < 256; word++)
+        for (const wake of wakes) {
+            const term = wake.words[word];
+            if (term)
+                wakeWords.push({ term, source: wake.kind, wakeIndex: wake.index });
+        }
+    const groups = [
+        wakeWords,
+        residentQueryWords(state.objective).map((term) => ({ term, source: 'objective' })),
+        residentQueryWords(state.summary ?? '').map((term) => ({
+            term,
+            source: 'derived_summary',
+        })),
+    ];
+    const selected = [];
+    const seen = new Set();
+    const offsets = [0, 0, 0];
+    for (let round = 0; round < 16; round++) {
+        for (const [i, group] of groups.entries()) {
+            while ((offsets[i] ?? 0) < group.length && selected.length < 16) {
+                const entry = group[offsets[i] ?? 0];
+                offsets[i] = (offsets[i] ?? 0) + 1;
+                if (!entry || seen.has(evidenceTokenKey(entry.term)))
+                    continue;
+                const terms = [...selected.map((item) => item.term), entry.term];
+                if (Buffer.byteLength(JSON.stringify({
+                    terms,
+                    ...(exclusions?.length ? { excludeSuccessfulTools: exclusions } : {}),
+                })) > 512)
+                    continue;
+                selected.push(entry);
+                seen.add(evidenceTokenKey(entry.term));
+                break;
+            }
+        }
+    }
+    const query = {
+        terms: selected.map(({ term }) => term),
+        metadata: {
+            kind: 'literal_resident_state',
+            terms: selected,
+            throughRevision: historicalScope.throughRevision,
+            guidance: 'Words select historical tool records only. Objective/wakes are accepted inputs; derived_summary is a prior claim, not a new observation. Selection may omit relevant words. Fields over 4000 characters contribute their first/last 2000 characters; terms alternate ends. Query/ranking do not resolve ambiguous references or establish truth, freshness or completeness. Use read_resident_tool with revision/address/byteOffset for exact retained text.',
+        },
+    };
+    const addresses = new WeakMap();
+    const search = source.search.bind(source);
+    const retrieve = async (request) => {
+        if (request.runId !== owner.runId)
+            throw new Error('Resident recall called from a different run.');
+        assertSource();
+        const candidates = [];
+        let scannedBytes = 0;
+        let incomplete = false;
+        const scans = [{ terms: request.terms, started: false }];
+        let excludedToolResults = 0;
+        for (let pageNumber = 0; pageNumber < 4; pageNumber++) {
+            const scan = [...scans].reverse().find((entry) => !entry.started || entry.cursor);
+            if (!scan)
+                break;
+            request.signal.throwIfAborted();
+            const allowance = request.maxReadBytes - scannedBytes;
+            if (allowance <= 1024 * 1024 || candidates.length >= request.maxCandidates)
+                break;
+            const page = await search({
+                ...(scan.cursor
+                    ? {
+                        cursor: scan.cursor,
+                        ...(scan.refineTerms ? { refineTerms: scan.refineTerms } : {}),
+                    }
+                    : {
+                        terms: [...scan.terms],
+                        ...(exclusions?.length ? { excludeSuccessfulTools: exclusions } : {}),
+                    }),
+                maxReadBytes: allowance,
+            }, request.signal);
+            request.signal.throwIfAborted();
+            assertSource();
+            if (JSON.stringify(historicalScopeSchema.parse(page.scope)) !== snapshot ||
+                !Number.isSafeInteger(page.chargedBytes) ||
+                (page.chargedBytes ?? -1) < 0 ||
+                (page.chargedBytes ?? Number.POSITIVE_INFINITY) > allowance ||
+                typeof page.incomplete !== 'boolean' ||
+                !Array.isArray(page.unavailableRevisions) ||
+                page.unavailableRevisions.some((revision) => !Number.isSafeInteger(revision) ||
+                    revision < 1 ||
+                    revision > historicalScope.throughRevision) ||
+                (page.nextCursor !== null &&
+                    (typeof page.nextCursor !== 'string' ||
+                        !page.nextCursor.length ||
+                        page.nextCursor.length > 8192)))
+                throw new Error('Resident recall received an invalid bounded page.');
+            scannedBytes += page.chargedBytes ?? 0;
+            // A page with a continuation is locally incomplete even when all
+            // records visited so far are valid. Clearing traversal later is safe;
+            // unavailable evidence stays incomplete for this entire pass.
+            incomplete ||=
+                (page.incomplete && !page.nextCursor) ||
+                    page.unavailableRevisions.length > 0 ||
+                    !!page.evidence?.incomplete;
+            const evidence = page.evidence;
+            if (evidence) {
+                const original = ownerSchema.parse(evidence.scope);
+                if (original.tenantId !== owner.tenantId ||
+                    original.projectId !== owner.projectId ||
+                    original.runId === owner.runId ||
+                    !Number.isSafeInteger(page.revision) ||
+                    (page.revision ?? 0) < 1 ||
+                    (page.revision ?? Number.POSITIVE_INFINITY) > historicalScope.throughRevision ||
+                    !z.string().uuid().safeParse(page.claimId).success ||
+                    page.claimId === state.claimId ||
+                    !Array.isArray(evidence.matches) ||
+                    evidence.matches.length > 24)
+                    throw new Error('Resident recall returned an unauthorized invocation.');
+                if (evidence.excludedToolResults !== undefined &&
+                    (!Number.isSafeInteger(evidence.excludedToolResults) || evidence.excludedToolResults < 0))
+                    throw new Error('Resident recall returned an invalid exclusion count.');
+                excludedToolResults += evidence.excludedToolResults ?? 0;
+                for (const match of evidence.matches) {
+                    if (typeof match.address !== 'string' ||
+                        !match.address.length ||
+                        match.address.length > 8192)
+                        throw new Error('Resident recall returned an invalid archive address.');
+                    const candidate = {
+                        scope: original,
+                        seq: match.seq,
+                        recordedAt: match.recordedAt,
+                        source: 'tool_completed',
+                        toolName: match.toolName,
+                        isError: match.isError,
+                        retained: match.retained,
+                        excerpt: match.excerpt,
+                        excerptComplete: match.excerptComplete,
+                        byteOffset: match.byteOffset,
+                    };
+                    addresses.set(candidate, {
+                        sessionId: original.sessionId,
+                        runId: original.runId,
+                        seq: match.seq,
+                        pursuitId: historicalScope.pursuitId,
+                        revision: page.revision,
+                        claimId: page.claimId,
+                        address: match.address,
+                        byteOffset: match.byteOffset,
+                    });
+                    candidates.push(candidate);
+                }
+            }
+            scan.started = true;
+            scan.cursor = page.nextCursor ?? undefined;
+            scan.refineTerms = undefined;
+            // One strict-subset scan spends the SAME page/byte allowance. Keep
+            // the broad cursor: finishing a subset never exhausts the full query.
+            if (scans.length === 1 &&
+                scan.cursor &&
+                pageNumber < 3 &&
+                (evidence?.matches.length ?? 0) >= 4) {
+                const focused = refineEvidenceRecallTerms(scan.terms, candidates.map((candidate) => candidate.excerpt));
+                if (focused)
+                    scans.push({
+                        terms: focused,
+                        started: false,
+                        ...(source.supportsTermRefinement === true
+                            ? { cursor: scan.cursor, refineTerms: focused }
+                            : {}),
+                    });
+            }
+        }
+        const continuations = scans.flatMap((scan) => scan.started && scan.cursor
+            ? [{ toolName: 'search_resident_tools', input: { cursor: scan.cursor } }]
+            : []);
+        return {
+            candidates,
+            scannedBytes,
+            incomplete: incomplete || scans.some((scan) => !scan.started || !!scan.cursor),
+            excludedToolResults,
+            continuations,
+        };
+    };
+    const step = createScopedEvidenceRecallStep({
+        retrieve,
+        maxChars: options.maxChars,
+        maxPassages: options.maxPassages,
+        timeoutMs: options.timeoutMs,
+    }, {
+        kind: 'resident',
+        selectQuery: () => query,
+        validate(candidate) {
+            assertSource();
+            if (!addresses.has(candidate))
+                throw new Error('Unowned resident evidence candidate.');
+        },
+        address(candidate) {
+            const address = addresses.get(candidate);
+            if (!address)
+                throw new Error('Missing resident evidence address.');
+            return address;
+        },
+    });
+    return async (context) => {
+        if (context.runId !== owner.runId)
+            throw new Error('Resident recall called from a different run.');
+        assertSource();
+        return step(context);
+    };
+}
+//# sourceMappingURL=evidence-recall.js.map

package/dist/manager/resident/evidence-recall.js.map

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

package/dist/manager/resident/history-disk.d.ts

@@ -0,0 +1,10 @@
+export interface ResidentHistoryReadBudget {
+    remaining: number;
+    bytesRead: number;
+    signal?: AbortSignal;
+}
+export declare class ResidentHistoryPageLimit extends Error {
+}
+/** Bounded read of an immutable record in a private host-owned hierarchy. */
+export declare function readResidentHistoryRecord(root: string, path: string, budget: ResidentHistoryReadBudget): Promise<unknown>;
+//# sourceMappingURL=history-disk.d.ts.map

package/dist/manager/resident/history-disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-disk.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/history-disk.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,yBAAyB;IACzC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;CAAG;AAEtD,6EAA6E;AAC7E,wBAAsB,yBAAyB,CAC9C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,yBAAyB,GAC/B,OAAO,CAAC,OAAO,CAAC,CA2ClB"}

package/dist/manager/resident/history-disk.js

@@ -0,0 +1,50 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+const RECORD_BYTES = 4 * 1024 * 1024;
+export class ResidentHistoryPageLimit extends Error {
+}
+/** Bounded read of an immutable record in a private host-owned hierarchy. */
+export async function readResidentHistoryRecord(root, path, budget) {
+    budget.signal?.throwIfAborted();
+    const base = resolve(root);
+    const suffix = relative(base, resolve(path));
+    if (suffix === '..' || suffix.startsWith(`..${sep}`))
+        throw new Error('Invalid history path.');
+    let current = base;
+    for (const part of ['', ...suffix.split(sep).filter(Boolean)]) {
+        current = join(current, part);
+        if ((await lstat(current)).isSymbolicLink())
+            throw new Error('History symlinks are refused.');
+    }
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > RECORD_BYTES)
+            throw new Error('History record is not a bounded regular file.');
+        if (before.size > budget.remaining)
+            throw new ResidentHistoryPageLimit();
+        const bytes = Buffer.alloc(before.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            budget.signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(bytes, offset, Math.min(64 * 1024, bytes.length - offset), offset);
+            budget.remaining -= bytesRead;
+            budget.bytesRead += bytesRead;
+            if (!bytesRead)
+                throw new Error('History record shortened during read.');
+            offset += bytesRead;
+        }
+        budget.signal?.throwIfAborted();
+        const after = await handle.stat();
+        if (after.size !== before.size ||
+            after.mtimeMs !== before.mtimeMs ||
+            after.ctimeMs !== before.ctimeMs)
+            throw new Error('History record changed during read.');
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=history-disk.js.map

package/dist/manager/resident/history-disk.js.map

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

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

@@ -0,0 +1,79 @@
+import type { ResidentAgendaState } from './agenda.js';
+import { type ResidentHistoryReadBudget } from './history-disk.js';
+/** @experimental Host-bound historical scope; the upper revision never advances implicitly. */
+export interface ResidentHistoryScope {
+    readonly tenantId: string;
+    readonly agentKey: string;
+    readonly pursuitId: string;
+    readonly throughRevision: number;
+}
+/** @experimental Revision plus part identifies retained text within one pursuit. */
+export interface ResidentHistoryAddress {
+    readonly revision: number;
+    readonly part: number;
+}
+/** @experimental Summary or accepted wake input from a settled historical step. */
+export interface ResidentHistoryMatch extends ResidentHistoryAddress {
+    readonly step: number;
+    readonly claimId: string;
+    readonly kind: 'wait' | 'complete' | 'blocked';
+    readonly source: 'summary' | 'wake';
+    readonly excerpt: string;
+    readonly matchingParts: readonly number[];
+}
+/** @experimental Empty query browses recent steps; cursor is the next inclusive revision. */
+export interface ResidentHistorySearchOptions {
+    /** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
+    readonly maxReadBytes?: number;
+    readonly query?: string;
+    readonly cursor?: number;
+    readonly limit?: number;
+}
+/** @experimental Counts describe this page, not the whole history. */
+export interface ResidentHistorySearchResult {
+    readonly matches: readonly ResidentHistoryMatch[];
+    readonly nextCursor: number | null;
+    readonly scannedRevisions: number;
+    readonly scannedBytes: number;
+    readonly unavailableRevisions: readonly number[];
+    readonly incomplete: boolean;
+}
+/** @experimental Use the returned nextOffset to continue exact Unicode-safe text. */
+export interface ResidentHistoryReadOptions extends ResidentHistoryAddress {
+    readonly offset?: number;
+    /** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
+    readonly maxReadBytes?: number;
+}
+/** @experimental A recorded claim remains historical evidence, not proof of current validity. */
+export interface ResidentHistoryText extends ResidentHistoryAddress {
+    readonly step: number;
+    readonly claimId: string;
+    readonly kind: 'wait' | 'complete' | 'blocked';
+    readonly source: 'summary' | 'wake';
+    readonly receivedAt?: number;
+    readonly text: string;
+    readonly offset: number;
+    readonly totalChars: number;
+    readonly nextOffset: number | null;
+}
+/** @experimental Null with unavailable revisions means unreadable evidence, not proven absence. */
+export interface ResidentHistoryReadResult {
+    readonly entry: ResidentHistoryText | null;
+    readonly scannedRevisions: number;
+    readonly scannedBytes: number;
+    readonly unavailableRevisions: readonly number[];
+}
+/** @experimental A backend must enforce its bound scope and bounded reads. */
+export interface ResidentHistorySource {
+    readonly scope: ResidentHistoryScope;
+    search(options?: ResidentHistorySearchOptions, signal?: AbortSignal): Promise<ResidentHistorySearchResult>;
+    read(options: ResidentHistoryReadOptions, signal?: AbortSignal): Promise<ResidentHistoryReadResult>;
+}
+type LoadRevision = (revision: number, budget: ResidentHistoryReadBudget) => Promise<ResidentAgendaState>;
+/** Internal disk adapter. Other backends may implement ResidentHistorySource directly. */
+export declare function createResidentHistorySource(scopeInput: ResidentHistoryScope, identity: {
+    identity: string;
+    objective: string;
+}, load: LoadRevision): ResidentHistorySource;
+export {};
+//# sourceMappingURL=history.d.ts.map

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

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