@namzu/sdk 38.1.0 → 39.0.0

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

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import type { ResidentAgendaState } from './agenda.js';
+export declare const residentObservationSchema: z.ZodObject<{
+    evidenceKey: z.ZodString;
+    source: z.ZodString;
+    progress: z.ZodNumber;
+    /** All observations and policy costs use the same host-defined resource unit. */
+    costUnits: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    evidenceKey: string;
+    progress: number;
+    costUnits: number | null;
+}, {
+    source: string;
+    evidenceKey: string;
+    progress: number;
+    costUnits: number | null;
+}>;
+/** @experimental Host-validated outcome and measured resource use, never model self-confidence. */
+export type ResidentObservation = Readonly<z.infer<typeof residentObservationSchema>>;
+export declare const residentFeedbackSchema: z.ZodObject<{
+    bestProgress: z.ZodNumber;
+    hasUnobservedSteps: z.ZodDefault<z.ZodBoolean>;
+    stagnantSteps: z.ZodNumber;
+    observations: z.ZodArray<z.ZodObject<{
+        evidenceKey: z.ZodString;
+        source: z.ZodString;
+        progress: z.ZodNumber;
+        /** All observations and policy costs use the same host-defined resource unit. */
+        costUnits: z.ZodNullable<z.ZodNumber>;
+    } & {
+        gain: z.ZodNumber;
+        step: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }, {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    observations: {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }[];
+    bestProgress: number;
+    hasUnobservedSteps: boolean;
+    stagnantSteps: number;
+}, {
+    observations: {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }[];
+    bestProgress: number;
+    stagnantSteps: number;
+    hasUnobservedSteps?: boolean | undefined;
+}>;
+/** @experimental Last eight observations; best progress and stagnation survive eviction. */
+export type ResidentFeedback = Readonly<Omit<z.infer<typeof residentFeedbackSchema>, 'observations'>> & {
+    readonly observations: readonly Readonly<z.infer<typeof residentFeedbackSchema>['observations'][number]>[];
+};
+export declare function observeResidentStep(previous: ResidentFeedback | undefined, input: ResidentObservation, step: number): ResidentFeedback;
+export declare function freezeResidentFeedback(value: ResidentFeedback): ResidentFeedback;
+/** @experimental Policy units are chosen by the host; scores are heuristics, not probabilities. */
+export interface ResidentSelectionConfig {
+    readonly progressValue: number;
+    readonly initialExpectedProgress: number;
+    readonly initialExpectedCost: number;
+    readonly maxStagnantSteps?: number;
+}
+/** @experimental Explainable inputs for a single selection; unknown cost is not zero. */
+export interface ResidentCandidate {
+    readonly pursuitId: string;
+    readonly reason: 'eligible' | 'not-due' | 'missing-observation' | 'stalled' | 'unknown-cost' | 'nonpositive-value';
+    readonly expectedGain: number | null;
+    readonly expectedCost: number | null;
+    readonly score: number | null;
+}
+/** @experimental Choice is bound to the whole agenda revision used to compute it. */
+export interface ResidentSelection {
+    readonly agendaRevision: number;
+    readonly pursuitId: string | null;
+    readonly reason: 'selected' | 'paused' | 'unresolved' | 'no-useful-work';
+    readonly candidates: readonly ResidentCandidate[];
+}
+/** @experimental Pure local selection; perform inference inside budgeted steps, not here. */
+export type ResidentSelector = (agenda: ResidentAgendaState, now: number) => ResidentSelection;
+/**
+ * @experimental Cost-aware continuation with an explicit abstention choice.
+ * This is a measured-progress heuristic, not Bayesian value of computation.
+ * A finite bootstrap allowance permits delayed payoffs but may stop too early.
+ */
+export declare function createResidentSelector(config: ResidentSelectionConfig): ResidentSelector;
+//# sourceMappingURL=initiative.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"initiative.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/initiative.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAItD,eAAO,MAAM,yBAAyB;;;;IAIrC,iFAAiF;;;;;;;;;;;;EAEhF,CAAA;AAEF,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC,CAAA;AAErF,eAAO,MAAM,sBAAsB;;;;;;;;QAPlC,iFAAiF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBhF,CAAA;AAEF,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CACtC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,EAAE,cAAc,CAAC,CAC5D,GAAG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CACvC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAC9D,EAAE,CAAA;CACH,CAAA;AAED,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,MAAM,GACV,gBAAgB,CAkBlB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAKhF;AAED,mGAAmG;AACnG,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAClC;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EACZ,UAAU,GACV,SAAS,GACT,qBAAqB,GACrB,SAAS,GACT,cAAc,GACd,mBAAmB,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,gBAAgB,CAAA;IACxE,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACjD;AAED,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,KAAK,iBAAiB,CAAA;AAc9F;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAkFxF"}

package/dist/manager/resident/initiative.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+const boundedText = z.string().trim().min(1).max(256);
+const cost = z.number().finite().nonnegative();
+export const residentObservationSchema = z.object({
+    evidenceKey: boundedText,
+    source: boundedText,
+    progress: z.number().finite().min(0).max(1),
+    /** All observations and policy costs use the same host-defined resource unit. */
+    costUnits: cost.nullable(),
+});
+export const residentFeedbackSchema = z.object({
+    bestProgress: z.number().finite().min(0).max(1),
+    hasUnobservedSteps: z.boolean().default(false),
+    stagnantSteps: z.number().int().nonnegative().safe(),
+    observations: z
+        .array(residentObservationSchema.extend({
+        gain: z.number().finite().min(0).max(1),
+        step: z.number().int().positive().safe(),
+    }))
+        .min(1)
+        .max(8),
+});
+export function observeResidentStep(previous, input, step) {
+    const observation = residentObservationSchema.parse(input);
+    const best = previous?.bestProgress ?? 0;
+    const duplicate = previous?.observations.some((item) => item.evidenceKey === observation.evidenceKey);
+    // Rewording evidence, regression and recovery to an old best earn no credit.
+    const gain = duplicate ? 0 : Math.max(0, observation.progress - best);
+    return freezeResidentFeedback(residentFeedbackSchema.parse({
+        bestProgress: best + gain,
+        hasUnobservedSteps: (previous?.hasUnobservedSteps ?? false) ||
+            step !== (previous?.observations.at(-1)?.step ?? 0) + 1,
+        stagnantSteps: gain > 0 ? 0 : (previous?.stagnantSteps ?? 0) + 1,
+        observations: [...(previous?.observations ?? []), { ...observation, gain, step }].slice(-8),
+    }));
+}
+export function freezeResidentFeedback(value) {
+    return Object.freeze({
+        ...value,
+        observations: Object.freeze(value.observations.map((item) => Object.freeze({ ...item }))),
+    });
+}
+function meanObservedCost(observations) {
+    // Null costs are rejected before this function. Scale by the largest finite
+    // observation: the intermediate sum is at most eight, even near MAX_VALUE.
+    const scale = Math.max(...observations.map((item) => item.costUnits ?? 0));
+    if (scale === 0)
+        return 0;
+    return ((observations.reduce((total, item) => total + (item.costUnits ?? 0) / scale, 0) /
+        observations.length) *
+        scale);
+}
+/**
+ * @experimental Cost-aware continuation with an explicit abstention choice.
+ * This is a measured-progress heuristic, not Bayesian value of computation.
+ * A finite bootstrap allowance permits delayed payoffs but may stop too early.
+ */
+export function createResidentSelector(config) {
+    const policy = z
+        .object({
+        progressValue: z.number().finite().positive(),
+        initialExpectedProgress: z.number().finite().positive().max(1),
+        initialExpectedCost: cost,
+        maxStagnantSteps: z.number().int().min(1).max(32).default(2),
+    })
+        .parse(config);
+    return (agenda, now) => {
+        z.number().int().nonnegative().safe().parse(now);
+        const finish = (pursuitId, reason, candidates) => Object.freeze({
+            agendaRevision: agenda.revision,
+            pursuitId,
+            reason,
+            candidates: Object.freeze(candidates.map((candidate) => Object.freeze(candidate))),
+        });
+        if (agenda.paused)
+            return finish(null, 'paused', []);
+        if (agenda.pursuits.some((p) => p.state.phase === 'running'))
+            return finish(null, 'unresolved', []);
+        const candidates = agenda.pursuits.map((p) => {
+            const reject = (reason) => ({
+                pursuitId: p.id,
+                reason,
+                expectedGain: null,
+                expectedCost: null,
+                score: null,
+            });
+            if (p.state.phase !== 'waiting' || p.state.wakeAt === null || p.state.wakeAt > now)
+                return reject('not-due');
+            if (p.state.stepsAdmitted > 0 &&
+                (!p.feedback ||
+                    p.feedback.hasUnobservedSteps ||
+                    p.feedback.observations.at(-1)?.step !== p.state.stepsAdmitted))
+                return reject('missing-observation');
+            const feedback = p.feedback;
+            if (feedback && feedback.stagnantSteps >= policy.maxStagnantSteps)
+                return reject('stalled');
+            if (feedback?.observations.some((item) => item.costUnits === null))
+                return reject('unknown-cost');
+            const recent = feedback?.observations ?? [];
+            const totalGain = recent.reduce((total, item) => total + item.gain, 0);
+            const bootstrap = p.state.stepsAdmitted < policy.maxStagnantSteps && totalGain === 0;
+            const expectedGain = recent.length === 0 || bootstrap
+                ? policy.initialExpectedProgress
+                : (totalGain + policy.initialExpectedProgress) / (recent.length + 1);
+            const expectedCost = recent.length === 0 ? policy.initialExpectedCost : meanObservedCost(recent);
+            const score = policy.progressValue * expectedGain - expectedCost;
+            return {
+                pursuitId: p.id,
+                reason: score > 0 ? 'eligible' : 'nonpositive-value',
+                expectedGain,
+                expectedCost,
+                score,
+            };
+        });
+        const eligible = candidates.filter((candidate) => candidate.reason === 'eligible');
+        eligible.sort((a, b) => {
+            const left = agenda.pursuits.find((p) => p.id === a.pursuitId);
+            const right = agenda.pursuits.find((p) => p.id === b.pursuitId);
+            if (!left || !right)
+                throw new Error('Resident candidate is missing.');
+            return ((b.score ?? 0) - (a.score ?? 0) ||
+                left.state.stepsAdmitted - right.state.stepsAdmitted ||
+                (left.state.wakeAt ?? 0) - (right.state.wakeAt ?? 0) ||
+                a.pursuitId.localeCompare(b.pursuitId));
+        });
+        return finish(eligible[0]?.pursuitId ?? null, eligible.length ? 'selected' : 'no-useful-work', candidates);
+    };
+}
+//# sourceMappingURL=initiative.js.map

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

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

package/dist/manager/resident/learning-cycle.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import { type HarnessProtectionPlan } from '../../eval/harness-protection.js';
+import { type HarnessReview, type HarnessVerificationBatch } from '../../eval/harness-verification.js';
+import type { DiskResidentAgenda } from './agenda.js';
+import { type ResidentLearningEvidence, type ResidentSkillCandidate } from './learning.js';
+/** @experimental One explicitly requested experiment; callbacks own inference and evaluation. */
+export type ResidentLearningStage = 'explore' | 'generate' | 'verification' | 'confirmation';
+declare const receiptSchema: z.ZodObject<{
+    runId: z.ZodString;
+    tokens: z.ZodNullable<z.ZodNumber>;
+    costUsd: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    runId: string;
+    tokens: number | null;
+    costUsd: number | null;
+}, {
+    runId: string;
+    tokens: number | null;
+    costUsd: number | null;
+}>;
+/** @experimental One non-overlapping execution's usage, including its retries. Null is unknown. */
+export type ResidentLearningReceipt = Readonly<z.infer<typeof receiptSchema>>;
+/** @experimental Recorded values are lower bounds when a receipt or stage is incomplete. */
+export interface ResidentLearningConsumption {
+    readonly tokens: number;
+    readonly costUsd: number;
+    readonly receipts: number;
+    readonly unknownTokens: number;
+    readonly unknownCosts: number;
+    readonly unfinishedStages: number;
+}
+/** @experimental Append in sequence to host-owned durable storage before acknowledging. */
+export interface ResidentLearningCycleEvent {
+    readonly cycleId: string;
+    readonly sequence: number;
+    readonly kind: 'started' | 'stage-started' | 'stage-finished' | 'usage' | 'exploration' | 'candidate' | 'evaluation' | 'activation-requested' | 'finished';
+    readonly stage?: ResidentLearningStage;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** @experimental Use this stage's signal for every owned run; await every usage append. */
+export interface ResidentLearningCycleContext {
+    readonly cycleId: string;
+    readonly stage: ResidentLearningStage;
+    readonly signal: AbortSignal;
+    /** Planning allowance, not a reservation or a cap on a callback's in-flight work. */
+    readonly remainingUnits: number;
+    recordUsage(receipt: ResidentLearningReceipt): Promise<void>;
+}
+/** @experimental Original failure and active baseline; never contains confirmation tasks. */
+export interface ResidentLearningExplorationContext extends ResidentLearningCycleContext {
+    readonly skillName: string;
+    /** Admitted by the host before generation; cannot be changed by a candidate. */
+    readonly purpose?: 'task' | 'exploration';
+    readonly failure: Readonly<{
+        evidence: ResidentLearningEvidence;
+        trace: string;
+    }>;
+    readonly baseline: ResidentSkillCandidate | null;
+}
+/** @experimental Host-retained environment observations, not a model's claim of success. */
+export interface ResidentLearningExploration {
+    readonly evidence: ResidentLearningEvidence;
+    readonly trace: string;
+}
+/** @experimental Generation sees completed exploration, never held-out evaluation cases. */
+export interface ResidentLearningGenerationContext extends ResidentLearningExplorationContext {
+    readonly exploration?: Readonly<ResidentLearningExploration>;
+}
+/** @experimental The host supplies independently scored, retained traces for these exact revisions. */
+export interface ResidentLearningEvaluationContext extends ResidentLearningCycleContext {
+    readonly baseline: ResidentSkillCandidate | null;
+    readonly candidate: ResidentSkillCandidate;
+    readonly baselineRevision: string;
+    readonly candidateRevision: string;
+}
+/** @experimental No provider, default background loop or executable-code activation is installed. */
+export interface ResidentLearningCycleOptions {
+    /** Omitted means task guidance. Explicitly select exploration to improve an explorer policy. */
+    readonly purpose?: 'task' | 'exploration';
+    /** Fixed before generation; both rounds must preserve every named task. */
+    readonly protection: HarnessProtectionPlan;
+    readonly agenda: Pick<DiskResidentAgenda, 'read' | 'promoteSkill'>;
+    readonly skillName: string;
+    readonly failure: {
+        readonly evidence: ResidentLearningEvidence;
+        readonly trace: string;
+    };
+    readonly parentCycleId?: string;
+    readonly signal: AbortSignal;
+    /** Stops subsequent stages/activation after observed excess; callbacks enforce in-flight limits. */
+    readonly resources: {
+        readonly unit: 'tokens' | 'usd';
+        readonly maxUnits: number;
+    };
+    readonly record: (event: ResidentLearningCycleEvent) => Promise<void>;
+    /** Optional active tool exploration before synthesis; the host retains actual observations. */
+    readonly explore?: (context: ResidentLearningExplorationContext) => Promise<{
+        readonly observations: ResidentLearningExploration;
+        readonly usageComplete: boolean;
+    }>;
+    readonly generate: (context: ResidentLearningGenerationContext) => Promise<{
+        readonly candidate: ResidentSkillCandidate;
+        /** All executions, including failures and side calls, have supplied receipts. */
+        readonly usageComplete: boolean;
+    }>;
+    readonly evaluate: (context: ResidentLearningEvaluationContext) => Promise<{
+        readonly batch: HarnessVerificationBatch;
+        readonly usageComplete: boolean;
+    }>;
+}
+/** @experimental An ambiguous activation must be inspected, never automatically replayed. */
+export interface ResidentLearningCycleResult {
+    readonly cycleId: string;
+    readonly status: 'activated' | 'rejected' | 'inconclusive' | 'conflict' | 'cancelled' | 'failed' | 'activation-unknown';
+    readonly reason: string;
+    readonly candidate?: ResidentSkillCandidate;
+    readonly candidateRevision?: string;
+    readonly baselineRevision?: string;
+    readonly agendaRevision?: number;
+    readonly review?: HarnessReview;
+    readonly consumption: ResidentLearningConsumption;
+    readonly auditComplete: boolean;
+}
+/**
+ * @experimental Generate one candidate, independently verify and confirm it, then
+ * activate through the existing exact-revision transaction. No internal inference
+ * loop, retry or model-generated success claim replaces the host's evaluator.
+ */
+export declare function runResidentLearningCycle(options: ResidentLearningCycleOptions): Promise<ResidentLearningCycleResult>;
+export {};
+//# sourceMappingURL=learning-cycle.d.ts.map

package/dist/manager/resident/learning-cycle.d.ts.map

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