@abot-ai/runtime 1.0.0

package/dist/src/runtime/steps/worker-decision/run.js

@@ -0,0 +1,433 @@
+import { invokeStructuredModelStep, StructuredModelInvalidOutputError, } from "../../model/invoke-structured-step.js";
+import { buildCompactedRequestToolResultsMessage, projectRequestToolResults, } from "../../context/request-tool-results.js";
+import { SEMANTIC_COMPACTION_CONTEXT_LANE, createSemanticCompactionSha256Fingerprint, projectSemanticCompactionDependencyResults, sameSemanticCompactionCheckpointBinding, } from "../../context/semantic-compaction/index.js";
+import { createModelStepCompactionController } from "../../context/model-step-compaction.js";
+import { emitRuntimeStatus } from "../../events/runtime-status.js";
+import { createWorkerCapabilityBinding, materializeWorkerCapabilityControlsIfComplete, partitionWorkerCapabilityControlsSchema, workerCapabilityContextCompactionScopeId, WORKER_CAPABILITY_CONTEXT_COMPACTION_ALLOWED_CONSUMERS, WORKER_CAPABILITY_RAW_PAYLOAD_MODEL_STEP, } from "../../orchestration/worker-capabilities/index.js";
+import { resolveRequestWorkerCapabilities, } from "../../request/execution-scope.js";
+import { classifyRuntimeErrorType } from "../../observability/error-type.js";
+import { projectWorkerDecisionCallIdentity, WORKER_DECISION_MODEL_STEP, } from "./contracts.js";
+import { traceWorkerClientBatchIntentsPublished, traceWorkerClientIntentPublished, traceWorkerCapabilityRefinementSkipped, traceWorkerCapabilitySelectionReopened, traceWorkerModelCompleted, traceWorkerModelFailed, traceWorkerModelStarted, } from "./diagnostics.js";
+import { buildWorkerDecisionInput, } from "./input.js";
+import { createWorkerCapabilitySelectionRejection, } from "./capability-selection-rejection.js";
+import { parseWorkerDecisionOutput } from "./parser.js";
+import { runWorkerResultAuthor } from "./result-author.js";
+import { projectEffectiveWorkerSelectionControlIds, projectEligibleWorkerSessionArtifactPaths, } from "./runtime-path-refinement.js";
+export async function runWorkerDecision(request, options) {
+    const decision = await runWorkerDecisionPhase(request, options);
+    const pendingCapabilitySelection = options.selectedCapabilityExecution
+        ? { kind: "single", selection: options.selectedCapabilityExecution }
+        : options.selectedCapabilityBatchExecution
+            ? { kind: "batch", selection: options.selectedCapabilityBatchExecution }
+            : undefined;
+    if (decision.action === "return_failure" &&
+        !options.capabilitySelectionRejection &&
+        pendingCapabilitySelection) {
+        const rejectedSelection = createCapabilitySelectionRejection(pendingCapabilitySelection, decision.reason);
+        traceWorkerCapabilitySelectionReopened({
+            diagnostic: {
+                requestId: request.requestId,
+                modelStep: WORKER_DECISION_MODEL_STEP,
+                decisionPhase: "capability_execution",
+                ...projectWorkerDecisionCallIdentity(options.call),
+            },
+            rejection: rejectedSelection.rejection,
+            reasonLength: rejectedSelection.reasonLength,
+        });
+        return runWorkerDecision(request, {
+            call: options.call,
+            requestToolResults: options.requestToolResults,
+            ...(options.capabilitySource
+                ? { capabilitySource: options.capabilitySource }
+                : {}),
+            ...(options.capabilityResume
+                ? { capabilityResume: options.capabilityResume }
+                : {}),
+            capabilitySelectionRejection: rejectedSelection.rejection,
+        });
+    }
+    if (decision.action === "return_result" ||
+        decision.action === "return_failure") {
+        return decision;
+    }
+    if (options.selectedCapabilityExecution) {
+        if (decision.action !== "invoke_capability") {
+            throw new Error("worker_capability_refinement_invalid");
+        }
+        if (!hasCapabilityControls(decision)) {
+            throw new Error("worker_capability_controls_missing");
+        }
+        return decision;
+    }
+    if (options.selectedCapabilityBatchExecution) {
+        if (decision.action !== "invoke_capabilities") {
+            throw new Error("worker_capability_batch_refinement_invalid");
+        }
+        if (!hasCapabilityBatchControls(decision)) {
+            throw new Error("worker_capability_batch_controls_missing");
+        }
+        return decision;
+    }
+    if (decision.action === "invoke_capability") {
+        assertGuidanceCapabilitiesInScope(options, [decision.capabilityId]);
+        const guidance = ((await resolveRequestWorkerCapabilities(request).provider.getExecutionGuidance?.(decision.capabilityId)) ?? "").trim();
+        if (guidance.length === 0) {
+            const descriptor = options.capabilitySource?.binding.capabilities.find(({ capabilityId }) => capabilityId === decision.capabilityId);
+            if (!descriptor) {
+                throw new Error("worker_capability_selection_descriptor_missing");
+            }
+            if (descriptor.controlsRefinement === "mechanical_when_complete") {
+                const eligibleSessionArtifactPaths = projectEligibleWorkerSessionArtifactPaths(request.sessionArtifactPaths, options.requestToolResults);
+                const effectiveSelectionControlIds = projectEffectiveWorkerSelectionControlIds(descriptor, eligibleSessionArtifactPaths.length > 0);
+                const partition = partitionWorkerCapabilityControlsSchema(descriptor.controls, effectiveSelectionControlIds);
+                if (!partition.ok) {
+                    throw new Error("worker_capability_controls_partition_invalid");
+                }
+                const selectionControls = "selectionControls" in decision && decision.selectionControls
+                    ? decision.selectionControls
+                    : Object.freeze({});
+                const materialized = materializeWorkerCapabilityControlsIfComplete(partition.value, selectionControls);
+                if (materialized) {
+                    if (!materialized.ok) {
+                        throw new Error("worker_capability_selection_controls_invalid");
+                    }
+                    traceWorkerCapabilityRefinementSkipped({
+                        diagnostic: {
+                            requestId: request.requestId,
+                            modelStep: WORKER_DECISION_MODEL_STEP,
+                            decisionPhase: "capability_execution",
+                            ...projectWorkerDecisionCallIdentity(options.call),
+                        },
+                        capabilityId: decision.capabilityId,
+                        selectionControlCount: Object.keys(selectionControls).length,
+                    });
+                    return Object.freeze({
+                        action: "invoke_capability",
+                        capabilityId: decision.capabilityId,
+                        intent: decision.intent,
+                        controls: materialized.value,
+                    });
+                }
+            }
+        }
+        return runWorkerDecision(request, {
+            ...options,
+            selectedCapabilityExecution: {
+                capabilityId: decision.capabilityId,
+                intent: decision.intent,
+                ...("selectionControls" in decision && decision.selectionControls
+                    ? { selectionControls: decision.selectionControls }
+                    : {}),
+                guidance,
+            },
+        });
+    }
+    const uniqueCapabilityIds = [
+        ...new Set(decision.invocations.map(({ capabilityId }) => capabilityId)),
+    ];
+    assertGuidanceCapabilitiesInScope(options, uniqueCapabilityIds);
+    const guidanceByCapabilityId = new Map(await Promise.all(uniqueCapabilityIds.map(async (capabilityId) => [
+        capabilityId,
+        ((await resolveRequestWorkerCapabilities(request).provider.getExecutionGuidance?.(capabilityId)) ?? "").trim(),
+    ])));
+    return runWorkerDecision(request, {
+        ...options,
+        selectedCapabilityBatchExecution: Object.freeze({
+            invocations: Object.freeze(decision.invocations.map(({ capabilityId, intent, ...invocationSelection }) => Object.freeze({
+                capabilityId,
+                intent,
+                ...("selectionControls" in invocationSelection &&
+                    invocationSelection.selectionControls
+                    ? {
+                        selectionControls: invocationSelection.selectionControls,
+                    }
+                    : {}),
+                guidance: guidanceByCapabilityId.get(capabilityId) ?? "",
+            }))),
+        }),
+    });
+}
+async function runWorkerDecisionPhase(request, options) {
+    const input = await prepareWorkerDecisionInput(request, options);
+    const diagnostic = input.diagnostic;
+    const startedAt = Date.now();
+    traceWorkerModelStarted({
+        diagnostic,
+        messageCount: input.context.messages.length,
+        messageCharacterCount: input.context.messages.reduce((total, message) => total + message.content.length, 0),
+        allowedActions: input.allowedActions,
+    });
+    let controlDecision;
+    try {
+        controlDecision = await invokeStructuredModelStep({
+            request,
+            modelStep: input.modelStep,
+            format: input.format,
+            messages: input.context.messages,
+            contextCompaction: createModelStepCompactionController(request, {
+                call: options.call,
+                sourceRevision: options.requestToolResults.sourceRevision,
+                allowedConsumers: WORKER_CAPABILITY_CONTEXT_COMPACTION_ALLOWED_CONSUMERS,
+                scopeId: workerCapabilityContextCompactionScopeId(options.call.callId),
+            }),
+            timeoutReason: "worker_decision_timeout",
+            invalidOutputReason: "invalid_worker_decision",
+            parse: (text) => {
+                const parsed = parseWorkerDecisionOutput(text, diagnostic, {
+                    availableCapabilities: input.availableCapabilities,
+                    maxBatchCapabilityExecutions: input.maxBatchCapabilityExecutions,
+                    decisionPhase: diagnostic.decisionPhase,
+                    ...(input.pendingCapabilitySelection
+                        ? {
+                            pendingCapabilitySelection: input.pendingCapabilitySelection,
+                        }
+                        : {}),
+                    ...(input.pendingCapabilityBatchSelection
+                        ? {
+                            pendingCapabilityBatchSelection: input.pendingCapabilityBatchSelection,
+                        }
+                        : {}),
+                });
+                return parsed;
+            },
+        });
+        traceWorkerModelCompleted({
+            diagnostic,
+            decision: controlDecision,
+            durationMs: Date.now() - startedAt,
+        });
+    }
+    catch (error) {
+        traceWorkerModelFailed({
+            diagnostic,
+            durationMs: Date.now() - startedAt,
+            errorType: classifyRuntimeErrorType(error),
+            invalidStructuredOutput: error instanceof StructuredModelInvalidOutputError,
+        });
+        throw error;
+    }
+    if (controlDecision.action !== "return_result") {
+        return controlDecision;
+    }
+    const resultAuthorSource = await completeWorkerHandoffEvidence(request, options, input);
+    const result = await runWorkerResultAuthor(request, {
+        diagnostic,
+        source: resultAuthorSource,
+    });
+    return Object.freeze({
+        action: "return_result",
+        result,
+    });
+}
+async function completeWorkerHandoffEvidence(request, options, input) {
+    const store = request.contextCompactionStore;
+    if (!store)
+        return input.resultAuthorSource;
+    const scopeId = workerCapabilityContextCompactionScopeId(options.call.callId);
+    const checkpoint = store.get(scopeId);
+    if (!checkpoint)
+        return input.resultAuthorSource;
+    assertWorkerCheckpointApplicable(request, options.call, checkpoint);
+    const prepared = await createModelStepCompactionController(request, {
+        call: options.call,
+        sourceRevision: options.requestToolResults.sourceRevision,
+        allowedConsumers: WORKER_CAPABILITY_CONTEXT_COMPACTION_ALLOWED_CONSUMERS,
+        scopeId,
+    }).prepare(input.context.messages);
+    prepared.commit();
+    const refreshedCheckpoint = store.get(scopeId);
+    if (!refreshedCheckpoint) {
+        throw new Error("context_compaction_handoff_checkpoint_missing");
+    }
+    assertWorkerCheckpointApplicable(request, options.call, refreshedCheckpoint);
+    return buildWorkerDecisionInput(request, {
+        ...options,
+        requestToolResultsContextMessage: buildCompactedRequestToolResultsMessage(options.requestToolResults, refreshedCheckpoint),
+    }).resultAuthorSource;
+}
+async function prepareWorkerDecisionInput(request, options) {
+    const store = request.contextCompactionStore;
+    const scopeId = workerCapabilityContextCompactionScopeId(options.call.callId);
+    const previous = store?.get(scopeId);
+    if (previous) {
+        assertWorkerCheckpointApplicable(request, options.call, previous);
+    }
+    return buildWorkerDecisionInput(request, {
+        ...options,
+        ...(previous
+            ? {
+                requestToolResultsContextMessage: buildCompactedRequestToolResultsMessage(options.requestToolResults, previous),
+            }
+            : {}),
+    });
+}
+function createWorkerCompactionBinding(request, call) {
+    return Object.freeze({
+        requestId: request.requestId,
+        currentRequestFingerprint: createSemanticCompactionSha256Fingerprint(request.prompt),
+        roleId: "worker",
+        callId: call.callId,
+        objectiveFingerprint: createSemanticCompactionSha256Fingerprint(call.objective),
+        contextLane: SEMANTIC_COMPACTION_CONTEXT_LANE,
+        allowedConsumers: WORKER_CAPABILITY_CONTEXT_COMPACTION_ALLOWED_CONSUMERS,
+    });
+}
+function assertWorkerCheckpointApplicable(request, call, checkpoint) {
+    if (!sameSemanticCompactionCheckpointBinding(checkpoint, createWorkerCompactionBinding(request, call))) {
+        throw new Error("context_compaction_checkpoint_not_applicable");
+    }
+}
+export const GENERIC_WORKER_EXECUTOR = Object.freeze({
+    roleId: "worker",
+    async execute({ context, call, ledger, continuation }) {
+        if (continuation?.kind === "role_child") {
+            throw new Error("worker_role_child_continuation_unsupported");
+        }
+        emitRuntimeStatus(context, {
+            stage: "worker",
+            phase: "working",
+            message: "Working on the delegated task...",
+        });
+        const head = ledger.current();
+        const dependencyResults = projectSemanticCompactionDependencyResults({
+            requestId: context.requestId,
+            prompt: context.prompt,
+            head,
+            call,
+            consumer: WORKER_CAPABILITY_RAW_PAYLOAD_MODEL_STEP,
+            ...(context.contextCompactionStore
+                ? { store: context.contextCompactionStore }
+                : {}),
+        });
+        const requestToolResults = projectRequestToolResults({
+            ledger,
+            head,
+            modelStep: WORKER_DECISION_MODEL_STEP,
+            callId: call.callId,
+        });
+        const workerCapabilities = resolveRequestWorkerCapabilities(context);
+        const binding = createWorkerCapabilityBinding({
+            requestId: context.requestId,
+            context: workerCapabilities.executionContext,
+            call,
+            ledger,
+            adapters: workerCapabilities.provider.getAdapters(),
+            ...(dependencyResults.length > 0 ? { dependencyResults } : {}),
+        });
+        const capabilitySource = {
+            binding,
+            ledger,
+            head,
+        };
+        const capabilityResume = continuation
+            ? {
+                ledger,
+                head,
+                ...(continuation.kind === "capability_batch_execution"
+                    ? { executionIds: continuation.executionIds }
+                    : { executionId: continuation.executionId }),
+            }
+            : undefined;
+        const decision = await runWorkerDecision(context, {
+            call,
+            requestToolResults,
+            capabilitySource,
+            ...(capabilityResume ? { capabilityResume } : {}),
+        });
+        if (decision.action === "return_result") {
+            return Object.freeze({
+                kind: "terminal",
+                outcome: "completed",
+                summary: decision.result,
+            });
+        }
+        if (decision.action === "return_failure") {
+            return Object.freeze({
+                kind: "terminal",
+                outcome: "failed",
+                summary: decision.reason,
+            });
+        }
+        if (decision.action === "invoke_capabilities") {
+            context.onThinkingDelta(`${decision.invocations.map(({ intent }) => intent).join("\n")}\n\n`);
+            traceWorkerClientBatchIntentsPublished({
+                diagnostic: {
+                    requestId: context.requestId,
+                    modelStep: WORKER_DECISION_MODEL_STEP,
+                    decisionPhase: "capability_execution",
+                    ...projectWorkerDecisionCallIdentity(call),
+                },
+                capabilityIds: decision.invocations.map(({ capabilityId }) => capabilityId),
+                intentLengths: decision.invocations.map(({ intent }) => intent.length),
+            });
+            const execution = await binding.executeBatch({
+                invocations: decision.invocations.map((invocation) => ({
+                    capabilityId: invocation.capabilityId,
+                    intent: invocation.intent,
+                    controls: invocation.controls,
+                })),
+            });
+            return Object.freeze({
+                kind: "continue",
+                continuation: Object.freeze({
+                    kind: "capability_batch_execution",
+                    executionIds: execution.executionIds,
+                }),
+            });
+        }
+        context.onThinkingDelta(`${decision.intent}\n\n`);
+        traceWorkerClientIntentPublished({
+            diagnostic: {
+                requestId: context.requestId,
+                modelStep: WORKER_DECISION_MODEL_STEP,
+                decisionPhase: "capability_execution",
+                ...projectWorkerDecisionCallIdentity(call),
+            },
+            capabilityId: decision.capabilityId,
+            intentLength: decision.intent.length,
+        });
+        const execution = await binding.execute({
+            capabilityId: decision.capabilityId,
+            intent: decision.intent,
+            controls: decision.controls,
+        });
+        return Object.freeze({
+            kind: "continue",
+            continuation: Object.freeze({
+                kind: "capability_execution",
+                executionId: execution.executionId,
+            }),
+        });
+    },
+});
+function assertGuidanceCapabilitiesInScope(options, capabilityIds) {
+    const availableCapabilityIds = new Set(options.capabilitySource?.binding.capabilities.map(({ capabilityId }) => capabilityId) ?? []);
+    if (!options.capabilitySource ||
+        capabilityIds.some((capabilityId) => !availableCapabilityIds.has(capabilityId))) {
+        throw new Error("worker_capability_guidance_out_of_scope");
+    }
+}
+function hasCapabilityControls(decision) {
+    return "controls" in decision;
+}
+function hasCapabilityBatchControls(decision) {
+    return decision.invocations.every((invocation) => "controls" in invocation);
+}
+function createCapabilitySelectionRejection(pendingSelection, reason) {
+    if (pendingSelection.kind === "single") {
+        return createWorkerCapabilitySelectionRejection({
+            rejectedSelectionKind: "single",
+            rejectedCapabilityIds: [pendingSelection.selection.capabilityId],
+            rejectedInvocationCount: 1,
+            reason,
+        });
+    }
+    return createWorkerCapabilitySelectionRejection({
+        rejectedSelectionKind: "batch",
+        rejectedCapabilityIds: [
+            ...new Set(pendingSelection.selection.invocations.map(({ capabilityId }) => capabilityId)),
+        ],
+        rejectedInvocationCount: pendingSelection.selection.invocations.length,
+        reason,
+    });
+}

package/dist/src/runtime/steps/worker-decision/runtime-path-refinement.d.ts

@@ -0,0 +1,5 @@
+import type { RequestToolResultsView } from "../../context/request-tool-results.js";
+import type { WorkerCapabilityDescriptor } from "../../orchestration/worker-capabilities/index.js";
+export declare const WORKER_SESSION_ARTIFACT_PATH_PROJECTION_MAX = 8;
+export declare function projectEligibleWorkerSessionArtifactPaths(sessionArtifactPaths: readonly string[] | undefined, requestToolResults: RequestToolResultsView): readonly string[];
+export declare function projectEffectiveWorkerSelectionControlIds(descriptor: Pick<WorkerCapabilityDescriptor, "selectionControlIds" | "runtimePathControlIds">, deferRuntimePathControls: boolean): readonly string[];

package/dist/src/runtime/steps/worker-decision/runtime-path-refinement.js

@@ -0,0 +1,30 @@
+export const WORKER_SESSION_ARTIFACT_PATH_PROJECTION_MAX = 8;
+export function projectEligibleWorkerSessionArtifactPaths(sessionArtifactPaths, requestToolResults) {
+    if (!sessionArtifactPaths || sessionArtifactPaths.length === 0) {
+        return Object.freeze([]);
+    }
+    const newestSessionArtifactPaths = sessionArtifactPaths.slice(0, WORKER_SESSION_ARTIFACT_PATH_PROJECTION_MAX);
+    const currentRequestTargets = new Set();
+    for (const result of requestToolResults.results) {
+        for (const reference of result.references ?? []) {
+            if (reference.kind === "tool_target") {
+                currentRequestTargets.add(reference.target);
+            }
+        }
+    }
+    return Object.freeze(newestSessionArtifactPaths.filter((target) => !currentRequestTargets.has(target)));
+}
+export function projectEffectiveWorkerSelectionControlIds(descriptor, deferRuntimePathControls) {
+    const selectionControlIds = descriptor.selectionControlIds ?? [];
+    if (!deferRuntimePathControls || selectionControlIds.length === 0) {
+        return selectionControlIds;
+    }
+    const runtimePathControlIds = new Set(descriptor.runtimePathControlIds ?? []);
+    if (runtimePathControlIds.size === 0) {
+        return selectionControlIds;
+    }
+    const effective = selectionControlIds.filter((controlId) => !runtimePathControlIds.has(controlId));
+    return effective.length === selectionControlIds.length
+        ? selectionControlIds
+        : Object.freeze(effective);
+}

package/dist/src/runtime/streaming/request-callbacks.d.ts

@@ -0,0 +1,25 @@
+import type WebSocket from "ws";
+import type { SessionThinkingTraceEntry } from "../../sessions/types.js";
+import type { RuntimeThinkingTrace } from "../model/thinking-trace.js";
+import type { EventSink, EventSinkFactory } from "../ports.js";
+import type { RequestSessionStore } from "../request/session-store.js";
+export declare function createInitialRequestEvents(params: {
+    eventSinkFactory: EventSinkFactory;
+    requestId: string;
+    ws: WebSocket;
+}): EventSink;
+export declare function createPersistentRequestEvents(params: {
+    currentEvents: EventSink;
+    eventSinkFactory: EventSinkFactory;
+    requestId: string;
+    sessionId: string;
+    sessionStore: RequestSessionStore;
+    ws: WebSocket;
+}): EventSink;
+export declare function createRequestCallbacks(events: EventSink): {
+    onAcknowledgement: (acknowledgement: string) => void;
+    onThinkingDelta: (delta: string) => void;
+    onThinkingTrace: (entry: RuntimeThinkingTrace) => void;
+    onAnswerToken: (token: string) => void;
+    getThinkingTrace: () => SessionThinkingTraceEntry[] | undefined;
+};

package/dist/src/runtime/streaming/request-callbacks.js

@@ -0,0 +1,52 @@
+export function createInitialRequestEvents(params) {
+    return params.eventSinkFactory.create({
+        requestId: params.requestId,
+        ws: params.ws,
+    });
+}
+export function createPersistentRequestEvents(params) {
+    params.currentEvents.dispose();
+    return params.eventSinkFactory.create({
+        requestId: params.requestId,
+        ws: params.ws,
+        persist: (payload) => params.sessionStore.appendRequestEvent(params.sessionId, params.requestId, payload),
+    });
+}
+export function createRequestCallbacks(events) {
+    let accumulatedAnswer = "";
+    let accumulatedThinking = "";
+    const thinkingTrace = [];
+    return {
+        onAcknowledgement: (acknowledgement) => {
+            const delta = `${acknowledgement}\n\n`;
+            events.thinkingDelta(delta, delta);
+        },
+        onThinkingDelta: (delta) => {
+            accumulatedThinking += delta;
+            events.thinkingDelta(delta, accumulatedThinking);
+        },
+        onThinkingTrace: (entry) => {
+            if (entry.text.trim().length > 0) {
+                thinkingTrace.push(entry);
+            }
+        },
+        onAnswerToken: (token) => {
+            if (!token) {
+                return;
+            }
+            accumulatedAnswer += token;
+            events.legacyToken(accumulatedAnswer);
+        },
+        getThinkingTrace: () => {
+            if (thinkingTrace.length === 0) {
+                return undefined;
+            }
+            return thinkingTrace.map((entry, index) => ({
+                sequence: index + 1,
+                step: entry.step,
+                status: entry.status,
+                text: entry.text,
+            }));
+        },
+    };
+}

package/dist/src/sessions/artifact-paths.d.ts

@@ -0,0 +1,9 @@
+import type { SessionArtifactPath, SessionArtifactPathInput } from "./types.js";
+export declare const MAX_SESSION_ARTIFACT_PATHS = 64;
+export declare const MAX_SESSION_ARTIFACT_PATH_TARGET_LENGTH = 4096;
+export declare function assertValidSessionArtifactPathInputs(inputs: readonly SessionArtifactPathInput[]): void;
+/**
+ * Keeps session artifact paths in oldest-to-newest recency order. Reusing an
+ * exact target refreshes its provenance and moves it to the newest position.
+ */
+export declare function upsertSessionArtifactPaths(existing: readonly SessionArtifactPath[], inputs: readonly SessionArtifactPathInput[], timestamp: string): SessionArtifactPath[];

package/dist/src/sessions/artifact-paths.js

@@ -0,0 +1,51 @@
+export const MAX_SESSION_ARTIFACT_PATHS = 64;
+export const MAX_SESSION_ARTIFACT_PATH_TARGET_LENGTH = 4096;
+export function assertValidSessionArtifactPathInputs(inputs) {
+    if (!Array.isArray(inputs)) {
+        throw new Error("session_artifact_path_inputs_invalid");
+    }
+    for (const input of inputs) {
+        if (!input ||
+            typeof input.target !== "string" ||
+            input.target.trim().length === 0) {
+            throw new Error("session_artifact_path_target_required");
+        }
+        if (input.target.length > MAX_SESSION_ARTIFACT_PATH_TARGET_LENGTH) {
+            throw new Error("session_artifact_path_target_too_long");
+        }
+        if (typeof input.sourceRequestId !== "string" ||
+            input.sourceRequestId.trim().length === 0) {
+            throw new Error("session_artifact_path_source_request_id_required");
+        }
+        if (typeof input.sourceExecutionId !== "string" ||
+            input.sourceExecutionId.trim().length === 0) {
+            throw new Error("session_artifact_path_source_execution_id_required");
+        }
+    }
+}
+/**
+ * Keeps session artifact paths in oldest-to-newest recency order. Reusing an
+ * exact target refreshes its provenance and moves it to the newest position.
+ */
+export function upsertSessionArtifactPaths(existing, inputs, timestamp) {
+    assertValidSessionArtifactPathInputs(inputs);
+    let next = existing.map((entry) => ({ ...entry }));
+    for (const input of inputs) {
+        const previous = findNewestExactTarget(next, input.target);
+        next = next.filter((entry) => entry.target !== input.target);
+        next.push({
+            ...input,
+            createdAt: previous?.createdAt ?? timestamp,
+            updatedAt: timestamp,
+        });
+    }
+    return next.slice(-MAX_SESSION_ARTIFACT_PATHS);
+}
+function findNewestExactTarget(entries, target) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        if (entries[index]?.target === target) {
+            return entries[index];
+        }
+    }
+    return undefined;
+}

package/dist/src/sessions/context-window.d.ts

@@ -0,0 +1,20 @@
+import type { SessionRecord, ToolObservationTaskResultRole } from "./types.js";
+import type { RuntimeAttachmentReference } from "../shared/attachments.js";
+export type ModelContextMessage = {
+    role: "user" | "assistant" | "system";
+    content: string;
+    attachments?: RuntimeAttachmentReference[];
+    contextMessageKind?: "prior_tool_observation" | "development_task_result_observation";
+    taskResultRole?: ToolObservationTaskResultRole;
+};
+export type ContextBuckets = {
+    recentConversation: ModelContextMessage[];
+    priorToolObservations: ModelContextMessage[];
+};
+export declare function buildContextBuckets(session: SessionRecord, options?: {
+    maxConversationMessages?: number;
+    maxToolObservationMessages?: number;
+    includeRecentConversation?: boolean;
+    includeRecentConversationAcrossTaskResults?: boolean;
+}): ContextBuckets;
+export declare function buildContextWindow(session: SessionRecord, maxMessages?: number): ModelContextMessage[];