@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/passive-learning/proactive/agent.js

@@ -0,0 +1,363 @@
+import { randomUUID } from "node:crypto";
+import { LearningAnalysisClock } from "../analysis-clock.js";
+import { isWithinAnalysisWindow, nextAnalysisInstant } from "../analysis-schedule.js";
+import { canDeliverProactiveProposal, hasProactiveReviewAttempt, isPendingProposalCurrent, isProactiveReviewEligible } from "./contracts.js";
+import { countProactiveDeliveries, createProactiveStateStore } from "./store.js";
+import { runStagedProactiveAgentReview } from "./staged-agent-review.js";
+import { canResumeStagedProactiveAttempt, hasCompletedStagedProactiveProgress, hasExpiredStagedProactiveProgress } from "./staged-progress-store.js";
+export class CoWorkerProactiveAgent {
+    options;
+    store;
+    clock;
+    started = false;
+    generation = 0;
+    active;
+    reviewNotBefore = 0;
+    retryNotBefore = 0;
+    reason;
+    controls = Promise.resolve();
+    armRevision = 0;
+    preferencesKey;
+    previousInterval = 0;
+    constructor(options) {
+        this.options = options;
+        this.store = createProactiveStateStore(options.directory);
+        this.clock = new LearningAnalysisClock(() => this.dispatch(), () => this.now());
+    }
+    async start() {
+        this.started = true;
+        this.preferencesKey = this.currentPreferencesKey();
+        this.previousInterval = this.interval();
+        this.reviewNotBefore = this.now() + this.interval();
+        await this.arm();
+    }
+    async stop() {
+        this.started = false;
+        this.armRevision += 1;
+        this.clock.clear(true);
+        this.active?.abort.abort(new Error("proactive_stopped"));
+        await this.active?.promise;
+    }
+    async preferencesChanged() {
+        await this.reschedulePreferences().catch((error) => this.fail(error));
+    }
+    async reschedulePreferences() {
+        const key = this.currentPreferencesKey();
+        if (key === this.preferencesKey)
+            return;
+        this.generation += 1;
+        this.armRevision += 1;
+        this.clock.clear(true);
+        this.active?.abort.abort(new Error("proactive_preferences_changed"));
+        await this.active?.promise;
+        const state = await this.store.read();
+        const profile = this.preferences().proactiveModelProfileId ?? this.preferences().modelProfileId;
+        if (this.canRetainStagedAttempt(state, profile))
+            await this.store.resumeStagedReviewAttempt();
+        else
+            await this.store.clearReviewAttempt();
+        if (hasExpiredStagedProactiveProgress(state, this.now()))
+            await this.store.expireReviewProgress(this.now());
+        this.reason = undefined;
+        if (!this.preferences().proactiveEnabled)
+            await this.store.cancelPending(this.now());
+        const intervalChanged = this.interval() !== this.previousInterval;
+        const retryNeedsRescheduling = intervalChanged && this.retryNotBefore > this.now();
+        if (intervalChanged)
+            this.reviewNotBefore = this.now() + this.interval();
+        if (retryNeedsRescheduling)
+            this.retryNotBefore = this.reviewNotBefore;
+        this.previousInterval = this.interval();
+        this.preferencesKey = key;
+        await this.arm();
+    }
+    knowledgeChanged() {
+        if (this.active?.delivering || this.active?.stagedReview) {
+            this.generation += 1;
+            this.active.abort.abort(new Error("proactive_superseded"));
+        }
+        void this.arm().catch((error) => this.fail(error));
+    }
+    beginInteractive() {
+        this.armRevision += 1;
+        this.clock.clear();
+        this.active?.abort.abort(new Error("proactive_interactive_preempted"));
+        return () => this.knowledgeChanged();
+    }
+    async dismiss(id) {
+        await this.store.dismiss(id, this.now());
+        this.options.context.changed();
+    }
+    async sessionDeleted(sessionId) {
+        const state = await this.store.read();
+        const proposal = state.proposals.find((item) => item.sessionId === sessionId);
+        if (proposal)
+            await this.dismiss(proposal.id);
+    }
+    async status() {
+        const [state, usage] = await Promise.all([this.store.read(), this.options.budget.status()]);
+        return { state: this.stateLabel(), proposals: state.proposals.slice(-20),
+            deliveredToday: countProactiveDeliveries(state, usage.startedAt),
+            ...(this.reason ? { reason: this.reason } : {}),
+            ...(this.clock.scheduledAt ? { nextReviewAt: new Date(this.clock.scheduledAt).toISOString() } : {}) };
+    }
+    dispatch() {
+        if (!this.canRun() || this.active)
+            return;
+        const abort = new AbortController();
+        const promise = Promise.resolve().then(() => this.run(abort.signal)).catch((error) => {
+            if (!abort.signal.aborted)
+                this.fail(error);
+        }).finally(() => {
+            this.active = undefined;
+            this.options.context.changed();
+            this.knowledgeChanged();
+        });
+        this.active = { abort, promise };
+        this.options.context.changed();
+    }
+    async run(signal) {
+        const generation = this.generation;
+        let state = await this.store.read();
+        if (this.usesStagedReview() && hasExpiredStagedProactiveProgress(state, this.now()))
+            state = await this.store.expireReviewProgress(this.now());
+        if (await this.deliverPending(state, signal, generation))
+            return;
+        const usage = await this.options.budget.status();
+        if (this.limitReached(state, usage, this.canCompleteSavedReview(state)))
+            return;
+        const context = await this.options.memory.overview();
+        const last = state.lastReviewedAt ? Date.parse(state.lastReviewedAt) : 0;
+        const eligible = isProactiveReviewEligible({ enabled: this.canRun(), insideWindow: this.insideWindow(),
+            interactiveBusy: this.options.context.isInteractiveBusy(), now: this.now(), nextAllowedAt: Math.max(this.retryNotBefore, this.reviewNotBefore, last + this.interval()),
+            knowledgeRevision: context.knowledgeRevision, hasKnowledge: context.entries.length > 0, state });
+        if (!eligible)
+            return;
+        this.reviewNotBefore = this.now() + this.interval();
+        const profile = this.preferences().proactiveModelProfileId ?? this.preferences().modelProfileId;
+        if (!profile)
+            throw new Error("proactive_model_required");
+        if (this.usesStagedReview()) {
+            if (this.active)
+                this.active.stagedReview = true;
+            const committed = await runStagedProactiveAgentReview({ state, context, profileId: profile,
+                store: this.store, memory: this.options.memory, model: this.options.model, signal,
+                now: () => this.now(), assertCurrent: () => this.assertCurrent(signal, generation) });
+            if (!committed)
+                return;
+            this.reason = undefined;
+            this.options.context.changed();
+            await this.deliverPending(committed, signal, generation);
+            return;
+        }
+        if (hasProactiveReviewAttempt(state, context.knowledgeRevision, profile))
+            return;
+        const reviewId = randomUUID();
+        const reserved = await this.store.reserveReviewAttempt({ reviewId, expectedRevision: state.revision,
+            knowledgeRevision: context.knowledgeRevision, profileId: profile, now: this.now(),
+            assertCurrent: () => this.assertCurrent(signal, generation) });
+        if (!reserved)
+            return;
+        let committed;
+        try {
+            const decision = await this.options.model.review({ reviewId, modelProfileId: profile,
+                context, recentProposals: state.proposals, signal });
+            signal.throwIfAborted();
+            // Window closure may settle this response, but cannot admit another call or delivery.
+            committed = await this.store.commitReview({ reviewId, expectedRevision: reserved.revision,
+                knowledgeRevision: context.knowledgeRevision, decision, now: this.now(),
+                assertCurrent: () => this.assertCurrent(signal, generation) });
+        }
+        catch (error) {
+            await this.store.failReviewAttempt(reviewId, safeFailure(error), signal.aborted || isRetryableReviewFailure(error));
+            throw error;
+        }
+        this.reason = undefined;
+        this.options.context.changed();
+        await this.deliverPending(committed, signal, generation);
+    }
+    async deliverPending(state, signal, generation) {
+        const pending = state.proposals.find((proposal) => isPendingProposalCurrent(proposal, this.now()));
+        if (!pending)
+            return false;
+        if (this.active)
+            this.active.delivering = true;
+        if (!this.insideWindow())
+            return true;
+        const usage = await this.options.budget.status();
+        const delivered = countProactiveDeliveries(state, usage.startedAt);
+        if (delivered >= (this.preferences().proactiveMessagesPerDay ?? 2)) {
+            this.reason = "proactive_daily_message_limit_reached";
+            return true;
+        }
+        const currentSources = await this.options.memory.sourceVersions();
+        if (!canDeliverProactiveProposal({ proposal: pending, enabled: this.canRun(), insideWindow: this.insideWindow(),
+            generationCurrent: generation === this.generation, now: this.now(), currentSources })) {
+            await this.store.cancelPending(this.now());
+            return true;
+        }
+        this.assertCurrent(signal, generation);
+        await this.deliver(pending, signal, generation);
+        return true;
+    }
+    deliver(proposal, signal, generation) {
+        const next = this.controls.then(async () => {
+            this.assertCurrent(signal, generation);
+            if (!this.insideWindow())
+                return;
+            if (!this.options.sessions.createAssistantConversation)
+                throw new Error("proactive_session_delivery_unavailable");
+            await this.options.sessions.createAssistantConversation(proposal.sessionId, {
+                title: proposal.title, content: proposal.message,
+                initiative: { kind: "proactive_proposal_v1", proposalId: proposal.id, reason: proposal.reason, sources: proposal.sources },
+                assertCurrent: () => {
+                    this.assertCurrent(signal, generation);
+                    if (!this.insideWindow())
+                        throw new Error("proactive_outside_window");
+                },
+            });
+            const usage = await this.options.budget.ensureCurrentWindow();
+            await this.store.markDelivered(proposal.id, this.now(), usage.startedAt);
+            if (this.canRun() && generation === this.generation && !signal.aborted)
+                this.options.context.changed({ type: "proposal_delivered", proposalId: proposal.id, sessionId: proposal.sessionId });
+        });
+        this.controls = next.catch(() => { });
+        return next;
+    }
+    async arm() {
+        const revision = ++this.armRevision;
+        const before = this.scheduleKey();
+        if (!this.canRun() || this.active)
+            return;
+        let state = await this.store.read();
+        if (this.usesStagedReview() && hasExpiredStagedProactiveProgress(state, this.now()))
+            state = await this.store.expireReviewProgress(this.now());
+        const context = await this.options.memory.overview();
+        const pending = state.proposals.some((proposal) => isPendingProposalCurrent(proposal, this.now()));
+        const profile = this.preferences().proactiveModelProfileId ?? this.preferences().modelProfileId;
+        const attempted = profile && hasProactiveReviewAttempt(state, context.knowledgeRevision, profile);
+        const resumable = this.usesStagedReview() && canResumeStagedProactiveAttempt(state);
+        if (!pending && attempted && !resumable) {
+            if (revision === this.armRevision) {
+                this.clock.clear();
+                this.reason = state.reviewAttempt?.reason ?? "proactive_review_interrupted";
+                this.publishScheduleChange(before);
+            }
+            return;
+        }
+        if (state.reviewAttempt && !attempted)
+            this.reason = undefined;
+        const newKnowledge = context.entries.length > 0 && context.knowledgeRevision !== state.reviewedKnowledgeRevision;
+        const hasReassessment = context.entries.length > 0 && state.nextReviewAt !== null;
+        if (!pending && !newKnowledge && !hasReassessment) {
+            if (revision === this.armRevision) {
+                this.clock.clear();
+                this.reason = undefined;
+                this.publishScheduleChange(before);
+            }
+            return;
+        }
+        const usage = await this.options.budget.status();
+        let earliest = Math.max(this.retryNotBefore, this.now());
+        if (!pending)
+            earliest = Math.max(earliest, this.reviewNotBefore);
+        if (state.lastReviewedAt && !pending)
+            earliest = Math.max(earliest, Date.parse(state.lastReviewedAt) + this.interval());
+        if (!pending && !newKnowledge && state.nextReviewAt)
+            earliest = Math.max(earliest, Date.parse(state.nextReviewAt));
+        if (this.limitReached(state, usage, pending || this.canCompleteSavedReview(state)))
+            earliest = Math.max(earliest, usage.resetsAt);
+        const due = nextAnalysisInstant(earliest, this.preferences().proactiveWindow);
+        if (!this.canRun() || this.active || revision !== this.armRevision)
+            return;
+        this.clock.clear();
+        this.clock.dispatched(due, 0);
+        this.clock.arm(this.now(), 0, this.preferences().proactiveWindow);
+        this.publishScheduleChange(before);
+    }
+    scheduleKey() { return `${this.reason ?? ""}:${this.clock.scheduledAt ?? ""}`; }
+    publishScheduleChange(previous) {
+        if (previous !== this.scheduleKey())
+            this.options.context.changed();
+    }
+    assertCurrent(signal, generation) {
+        signal.throwIfAborted();
+        if (!this.canRun() || generation !== this.generation)
+            throw new Error("proactive_superseded");
+    }
+    limitReached(state, usage, pending = false) {
+        if (countProactiveDeliveries(state, usage.startedAt) >= (this.preferences().proactiveMessagesPerDay ?? 2)) {
+            this.reason = "proactive_daily_message_limit_reached";
+            return true;
+        }
+        if (!pending && usage.modelCalls >= (this.preferences().resourceLimits?.modelCallsPerDay ?? 24)) {
+            this.reason = "co_worker_model_daily_budget_exhausted";
+            return true;
+        }
+        if (this.reason === "proactive_daily_message_limit_reached" || this.reason === "co_worker_model_daily_budget_exhausted")
+            this.reason = undefined;
+        return false;
+    }
+    canRun() {
+        if (!this.started || !this.options.context.isStarted())
+            return false;
+        if (!this.preferences().proactiveEnabled)
+            return false;
+        return !this.options.context.isInteractiveBusy();
+    }
+    insideWindow() { return isWithinAnalysisWindow(this.now(), this.preferences().proactiveWindow); }
+    preferences() { return this.options.context.preferences(); }
+    usesStagedReview() {
+        const profile = this.preferences().proactiveModelProfileId ?? this.preferences().modelProfileId;
+        if (!profile)
+            return false;
+        return this.options.model.reviewMethod?.(profile) === "staged";
+    }
+    canRetainStagedAttempt(state, profile) {
+        if (!this.usesStagedReview())
+            return false;
+        if (state.reviewAttempt?.method !== "super-v2")
+            return false;
+        return state.reviewAttempt.profileId === profile;
+    }
+    canCompleteSavedReview(state) {
+        if (!this.usesStagedReview())
+            return false;
+        return hasCompletedStagedProactiveProgress(state, this.now());
+    }
+    currentPreferencesKey() {
+        const value = this.preferences();
+        return JSON.stringify([value.proactiveEnabled, value.proactiveModelProfileId ?? value.modelProfileId,
+            value.proactiveIntervalMinutes, value.proactiveWindow, value.proactiveMessagesPerDay, value.resourceLimits]);
+    }
+    interval() { return (this.preferences().proactiveIntervalMinutes ?? 60) * 60_000; }
+    now() { return (this.options.now ?? Date.now)(); }
+    fail(error) {
+        this.retryNotBefore = this.now() + this.interval();
+        this.reason = safeFailure(error);
+        this.options.context.changed();
+    }
+    stateLabel() {
+        if (!this.preferences().proactiveEnabled)
+            return "off";
+        if (this.active)
+            return "reviewing";
+        if (this.reason?.includes("budget_exhausted"))
+            return "budget_limited";
+        if (this.reason === "proactive_daily_message_limit_reached")
+            return "budget_limited";
+        if (this.reason)
+            return "failed";
+        return "waiting";
+    }
+}
+function safeFailure(error) {
+    const code = error instanceof Error ? error.message : "";
+    return /^[a-z][a-z0-9_]{0,100}$/u.test(code) ? code : "proactive_failed";
+}
+function isRetryableReviewFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    return ["co_worker_model_daily_budget_exhausted", "co_worker_resources_busy", "proactive_outside_window",
+        "proactive_disabled", "proactive_superseded", "proactive_revision_conflict"].includes(error.message);
+}

package/dist/src/runtime/passive-learning/proactive/contracts.d.ts

@@ -0,0 +1,90 @@
+import type { LearningKnowledgeContext, LearningKnowledgeEntry } from "../../long-term-memory/maturation/contracts.js";
+import type { CoWorkerReviewProgress, ReviewProgressPort } from "../review-progress.js";
+export declare const MAX_PROACTIVE_RECEIPTS = 100;
+export declare const MAX_PROACTIVE_STATE_BYTES: number;
+export declare const MAX_PROACTIVE_FUTURE_MS: number;
+export type ProactiveSourceReference = Readonly<{
+    kind: "candidate" | "memory";
+    id: string;
+    version: string;
+}>;
+export type ProactiveDecision = Readonly<{
+    kind: "none" | "proposal";
+    title: string | null;
+    message: string | null;
+    reason: string;
+    sources: readonly ProactiveSourceReference[];
+    expiresAt: string | null;
+    reconsiderAt: string | null;
+}>;
+export type ProactiveProposal = Readonly<{
+    id: string;
+    reviewId: string;
+    sessionId: string;
+    knowledgeRevision: number;
+    title: string;
+    message: string;
+    reason: string;
+    sources: readonly ProactiveSourceReference[];
+    createdAt: string;
+    expiresAt: string;
+    status: "pending" | "delivered" | "dismissed" | "cancelled";
+    settledAt: string | null;
+}>;
+export type ProactiveReviewAttempt = Readonly<{
+    reviewId: string;
+    knowledgeRevision: number;
+    profileId: string;
+    status: "running" | "failed";
+    method?: "super-v2";
+    reason?: string;
+}>;
+export type ProactiveState = Readonly<{
+    schemaVersion: 1;
+    revision: number;
+    lastReviewId: string | null;
+    reviewedKnowledgeRevision: number | null;
+    lastReviewedAt: string | null;
+    nextReviewAt: string | null;
+    deliveryUsage?: Readonly<{
+        startedAt: number;
+        deliveredCount: number;
+    }>;
+    reviewAttempt?: ProactiveReviewAttempt;
+    reviewProgress?: CoWorkerReviewProgress;
+    proposals: readonly ProactiveProposal[];
+}>;
+/** A crashed or failed paid attempt cannot automatically replay unchanged knowledge. */
+export declare function hasProactiveReviewAttempt(state: ProactiveState, knowledgeRevision: number, profileId: string): boolean;
+export type ProactiveReviewInput = Readonly<{
+    reviewId: string;
+    modelProfileId: string;
+    context: LearningKnowledgeContext;
+    recentProposals: readonly ProactiveProposal[];
+    signal: AbortSignal;
+    progress?: ReviewProgressPort;
+}>;
+/** Cadence, window and budget remain separate admission gates. */
+export declare function isProactiveReviewEligible(input: Readonly<{
+    enabled: boolean;
+    insideWindow: boolean;
+    interactiveBusy: boolean;
+    now: number;
+    nextAllowedAt: number;
+    knowledgeRevision: number;
+    hasKnowledge: boolean;
+    state: ProactiveState;
+}>): boolean;
+export declare function isPendingProposalCurrent(proposal: ProactiveProposal, now: number): boolean;
+export declare function canDeliverProactiveProposal(input: Readonly<{
+    proposal: ProactiveProposal;
+    enabled: boolean;
+    insideWindow: boolean;
+    generationCurrent: boolean;
+    now: number;
+    currentSources: readonly ProactiveSourceReference[];
+}>): boolean;
+export declare function hasExactProactiveSource(entries: readonly Pick<LearningKnowledgeEntry, "kind" | "id" | "version">[], source: ProactiveSourceReference): boolean;
+export declare function validateProactiveDecision(value: unknown, entries: readonly ProactiveSourceReference[], now: number): ProactiveDecision;
+export declare function validateProactiveFutureInstant(value: unknown, now: number): void;
+export declare function isBoundedProactiveText(value: unknown, maximum: number): value is string;

package/dist/src/runtime/passive-learning/proactive/contracts.js

@@ -0,0 +1,136 @@
+export const MAX_PROACTIVE_RECEIPTS = 100;
+export const MAX_PROACTIVE_STATE_BYTES = 2 * 1024 * 1024;
+export const MAX_PROACTIVE_FUTURE_MS = 30 * 86_400_000;
+/** A crashed or failed paid attempt cannot automatically replay unchanged knowledge. */
+export function hasProactiveReviewAttempt(state, knowledgeRevision, profileId) {
+    if (!state.reviewAttempt)
+        return false;
+    if (state.reviewAttempt.knowledgeRevision !== knowledgeRevision)
+        return false;
+    return state.reviewAttempt.profileId === profileId;
+}
+/** Cadence, window and budget remain separate admission gates. */
+export function isProactiveReviewEligible(input) {
+    if (!input.enabled)
+        return false;
+    if (!input.insideWindow)
+        return false;
+    if (input.interactiveBusy)
+        return false;
+    if (!input.hasKnowledge)
+        return false;
+    if (input.now < input.nextAllowedAt)
+        return false;
+    if (input.state.proposals.some((proposal) => isPendingProposalCurrent(proposal, input.now)))
+        return false;
+    if (input.state.reviewedKnowledgeRevision !== input.knowledgeRevision)
+        return true;
+    if (!input.state.nextReviewAt)
+        return false;
+    return Date.parse(input.state.nextReviewAt) <= input.now;
+}
+export function isPendingProposalCurrent(proposal, now) {
+    if (proposal.status !== "pending")
+        return false;
+    return Date.parse(proposal.expiresAt) > now;
+}
+export function canDeliverProactiveProposal(input) {
+    if (!input.enabled)
+        return false;
+    if (!input.insideWindow)
+        return false;
+    if (!input.generationCurrent)
+        return false;
+    if (!isPendingProposalCurrent(input.proposal, input.now))
+        return false;
+    if (!input.proposal.sources.length)
+        return false;
+    return input.proposal.sources.every((source) => hasExactProactiveSource(input.currentSources, source));
+}
+export function hasExactProactiveSource(entries, source) {
+    return entries.some((entry) => entry.kind === source.kind &&
+        entry.id === source.id &&
+        entry.version === source.version);
+}
+export function validateProactiveDecision(value, entries, now) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("proactive_decision_invalid");
+    const decision = value;
+    if (decision.kind !== "none" && decision.kind !== "proposal")
+        throw new Error("proactive_decision_invalid");
+    if (!isBoundedProactiveText(decision.reason, 1000))
+        throw new Error("proactive_reason_invalid");
+    if (!Array.isArray(decision.sources) || decision.sources.length > 12)
+        throw new Error("proactive_sources_invalid");
+    const sources = decision.sources.map((source) => {
+        if (!source || typeof source !== "object")
+            throw new Error("proactive_source_invalid");
+        if (!hasExactProactiveSource(entries, source))
+            throw new Error("proactive_source_stale_or_unknown");
+        return Object.freeze({
+            kind: source.kind,
+            id: source.id,
+            version: source.version,
+        });
+    });
+    if (new Set(sources.map((source) => `${source.kind}:${source.id}`)).size !==
+        sources.length)
+        throw new Error("proactive_source_duplicate");
+    validateProactiveFutureInstant(decision.reconsiderAt, now);
+    if (decision.kind === "none") {
+        if (decision.title !== null ||
+            decision.message !== null ||
+            decision.expiresAt !== null ||
+            sources.length)
+            throw new Error("proactive_none_payload_invalid");
+        return Object.freeze({
+            kind: decision.kind,
+            title: null,
+            message: null,
+            reason: decision.reason,
+            sources,
+            expiresAt: null,
+            reconsiderAt: decision.reconsiderAt,
+        });
+    }
+    if (!isBoundedProactiveText(decision.title, 160))
+        throw new Error("proactive_title_invalid");
+    if (!isBoundedProactiveText(decision.message, 4000))
+        throw new Error("proactive_message_invalid");
+    if (!sources.length)
+        throw new Error("proactive_sources_required");
+    if (decision.expiresAt === null)
+        throw new Error("proactive_expiry_required");
+    validateProactiveFutureInstant(decision.expiresAt, now);
+    return Object.freeze({
+        kind: decision.kind,
+        title: decision.title,
+        message: decision.message,
+        reason: decision.reason,
+        sources,
+        expiresAt: decision.expiresAt,
+        reconsiderAt: decision.reconsiderAt,
+    });
+}
+export function validateProactiveFutureInstant(value, now) {
+    if (!Number.isFinite(now))
+        throw new Error("proactive_reference_time_invalid");
+    if (value === null)
+        return;
+    if (typeof value !== "string")
+        throw new Error("proactive_time_invalid");
+    const instant = Date.parse(value);
+    if (!Number.isFinite(instant))
+        throw new Error("proactive_time_invalid");
+    if (instant <= now)
+        throw new Error("proactive_time_not_future");
+    if (instant - now > MAX_PROACTIVE_FUTURE_MS)
+        throw new Error("proactive_time_too_distant");
+}
+export function isBoundedProactiveText(value, maximum) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.trim())
+        return false;
+    return value.length <= maximum;
+}

package/dist/src/runtime/passive-learning/proactive/model-output.d.ts

@@ -0,0 +1,3 @@
+import { type ProactiveDecision, type ProactiveReviewInput } from "./contracts.js";
+/** Explanation is optional model metadata, not evidence or permission to act. */
+export declare function decodeProactiveModelDecision(text: string, input: ProactiveReviewInput): ProactiveDecision;

package/dist/src/runtime/passive-learning/proactive/model-output.js

@@ -0,0 +1,52 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+import { validateProactiveDecision } from "./contracts.js";
+/** Explanation is optional model metadata, not evidence or permission to act. */
+export function decodeProactiveModelDecision(text, input) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        traceDebug("runtime.passive_learning", "proactive.output_rejected", {
+            requestId: `proactive:${input.reviewId}`, reviewId: input.reviewId, modelProfileId: input.modelProfileId,
+            outputCharacters: text.length, reason: "proactive_output_invalid_json",
+        });
+        throw new Error("proactive_output_invalid_json");
+    }
+    const object = proactiveOutputObject(value);
+    const explanation = normalizeProactiveExplanation(object?.reason);
+    const diagnostics = {
+        requestId: `proactive:${input.reviewId}`, reviewId: input.reviewId, modelProfileId: input.modelProfileId,
+        outputCharacters: text.length, reasonState: explanation.state,
+        reasonCharacters: typeof object?.reason === "string" ? object.reason.length : null,
+    };
+    try {
+        const decision = validateProactiveDecision(object ? { ...object, reason: explanation.text } : value, input.context.entries, Date.parse(input.context.referenceTime));
+        traceDebug("runtime.passive_learning", "proactive.output_accepted", { ...diagnostics, kind: decision.kind });
+        return decision;
+    }
+    catch (error) {
+        const reason = error instanceof Error && /^proactive_[a-z_]+$/u.test(error.message)
+            ? error.message : "proactive_decision_invalid";
+        traceDebug("runtime.passive_learning", "proactive.output_rejected", { ...diagnostics, reason });
+        throw error;
+    }
+}
+function proactiveOutputObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function normalizeProactiveExplanation(value) {
+    const omitted = { text: "No explanation provided by the model.", state: "omitted" };
+    if (value === null || value === undefined)
+        return omitted;
+    if (typeof value !== "string")
+        return { ...omitted, state: "invalid_type" };
+    const text = value.trim();
+    if (!text)
+        return { ...omitted, state: "empty" };
+    if (text.length > 1000)
+        return { text: text.slice(0, 1000), state: "truncated" };
+    return { text, state: "provided" };
+}