@myagentroam/agent 0.11.32 → 0.11.34

package/dist/runtime/compaction/requests.js

@@ -0,0 +1,114 @@
+import { AsyncQueue } from '../async-queue.js';
+import { AgentError, describeAgentError } from '../../error.js';
+/** External handles represent an operation inside its owning main Execution, not another loop. */
+export class CompactRequests {
+    executionId;
+    assertAdmission;
+    #closed = false;
+    #blocking = false;
+    #join;
+    #pending = [];
+    #observers = new Set();
+    constructor(executionId, assertAdmission) {
+        this.executionId = executionId;
+        this.assertAdmission = assertAdmission;
+    }
+    request(input) {
+        this.assertAdmission();
+        if (this.#closed)
+            throw new AgentError('MAR_AGENT_SESSION_INPUT_CLOSED', 'Execution is finishing.');
+        if (Object.entries(input).some(([key, value]) => value !== undefined && !['prompt', 'async'].includes(key)))
+            throw new AgentError('MAR_AGENT_COMPACT_CONFLICT', 'An active compaction uses its owning execution configuration.');
+        if (input.async !== undefined && typeof input.async !== 'boolean')
+            throw new AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Compaction async mode is invalid.');
+        const queue = new AsyncQueue();
+        let resolve;
+        const result = new Promise((settle) => {
+            resolve = settle;
+        });
+        let settled = false;
+        let operationId;
+        const observe = (event) => {
+            if ('compactionId' in event && event.compactionId === operationId)
+                queue.push(event);
+        };
+        this.#observers.add(observe);
+        const finish = (status, error) => {
+            if (settled)
+                return;
+            settled = true;
+            const diagnostic = error === undefined ? undefined : describeAgentError(error, 'MAR_AGENT_COMPACT_FAILED');
+            resolve({
+                executionId: this.executionId,
+                status,
+                finalAnswer: '',
+                ...(diagnostic ? { errorCode: diagnostic.code, errorMessage: diagnostic.message } : {})
+            });
+            this.#observers.delete(observe);
+            queue.close();
+        };
+        const pending = {
+            input: { ...input },
+            cancelled: () => settled,
+            settle: (flight) => {
+                operationId = flight.id;
+                void flight.result.then((changed) => finish(changed ? 'completed' : 'failed', changed
+                    ? undefined
+                    : new AgentError('MAR_AGENT_CONTEXT_LIMIT', 'No history can be compacted.')), (error) => finish('failed', error));
+            },
+            fail: (error) => finish('failed', error)
+        };
+        try {
+            const flight = this.#join?.(input);
+            if (flight) {
+                pending.settle(flight);
+                this.#blocking ||= input.async !== true;
+            }
+            else
+                this.#pending.push(pending);
+        }
+        catch (error) {
+            pending.fail(error);
+        }
+        return {
+            executionId: this.executionId,
+            [Symbol.asyncIterator]: () => queue[Symbol.asyncIterator](),
+            result: () => {
+                queue.discardIfUnobserved();
+                return result;
+            },
+            cancel: () => finish('cancelled')
+        };
+    }
+    publish(event) {
+        for (const observer of this.#observers)
+            observer(event);
+    }
+    bind(join) {
+        this.#join = join;
+    }
+    drain(start) {
+        let blocking = this.#blocking;
+        this.#blocking = false;
+        for (const pending of this.#pending.splice(0)) {
+            if (pending.cancelled())
+                continue;
+            try {
+                pending.settle(start(pending.input));
+                blocking ||= pending.input.async !== true;
+            }
+            catch (error) {
+                pending.fail(error);
+            }
+        }
+        return blocking;
+    }
+    seal() {
+        this.#closed = true;
+    }
+    close(error) {
+        this.seal();
+        for (const pending of this.#pending.splice(0))
+            pending.fail(error);
+    }
+}

package/dist/runtime/compaction/retained-context.d.ts

@@ -0,0 +1,6 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import type { CompactSnapshotAnchor } from '../events.js';
+/** Use a public native identity, never private context text, as the visible boundary. */
+export declare function compactSnapshotAnchor(messages: readonly ModelMessage[], sources: WeakMap<ModelMessage, import('../../session/record-contract.js').SessionRecord>): CompactSnapshotAnchor | undefined;
+/** Decode the SDK-owned checkpoint suffix without promoting contextual text to real input. */
+export declare function restoreCompactTail(value: unknown): ModelMessage | undefined;

package/dist/runtime/compaction/retained-context.js

@@ -0,0 +1,48 @@
+import { parseModelInputMetadata } from '../../session/record-projection.js';
+import { restoreModelContext } from '../context/projection.js';
+import { parseModelImages } from '../../model/image.js';
+/** Use a public native identity, never private context text, as the visible boundary. */
+export function compactSnapshotAnchor(messages, sources) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role === 'tool' && message.callId)
+            return { kind: 'tool', id: message.callId };
+        const record = sources.get(message);
+        const payload = record?.payload;
+        if (record?.type === 'message.completed' && typeof payload?.itemId === 'string')
+            return { kind: 'message', id: payload.itemId };
+    }
+    return undefined;
+}
+/** Decode the SDK-owned checkpoint suffix without promoting contextual text to real input. */
+export function restoreCompactTail(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const input = value;
+    if ((input.contextKind === 'private' && input.role !== 'provider') ||
+        input.contextKind === 'compact_control')
+        return undefined;
+    if ((input.role === 'assistant' || input.role === 'user') && typeof input.content === 'string') {
+        if (input.inputRef !== undefined)
+            return restoreModelContext(input);
+        const projected = restoreModelContext(input);
+        const metadata = parseModelInputMetadata(input.metadata);
+        const images = parseModelImages(input.images);
+        const contextKind = ['environment', 'contextual', 'summary'].includes(String(input.contextKind))
+            ? input.contextKind
+            : undefined;
+        return {
+            role: input.role,
+            content: input.content,
+            ...(contextKind
+                ? { contextKind }
+                : input.role === 'user' && !metadata
+                    ? { contextKind: 'contextual' }
+                    : {}),
+            ...(metadata ? { metadata } : {}),
+            ...(projected?.textBlocks ? { textBlocks: projected.textBlocks } : {}),
+            ...(images?.length ? { images } : {})
+        };
+    }
+    return restoreModelContext(input);
+}

package/dist/runtime/compaction/smart.d.ts

@@ -0,0 +1,14 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import type { SessionRecord } from '../../session/record-contract.js';
+export declare const SMART_COMPACTION_MARKER = "<mar_runtime>\n  <smart_compaction>For this message only, smart_compact may be considered at a clear transition into sustained new work, when the previous phase is largely complete and its details have low continuation value.</smart_compaction>\n</mar_runtime>";
+export interface SmartCompactionInput {
+    readonly recordId: string;
+    readonly eligible: boolean;
+    requested: boolean;
+    error?: unknown;
+}
+/** A measured watermark, not the stricter native-request budget calibration. */
+export declare function latestSmartContextTokens(records: readonly SessionRecord[], modelId: string, contextWindowTokens: number): number | undefined;
+/** Only provider views receive the marker; durable message content stays unchanged. */
+export declare function projectSmartCompactionMessage(message: ModelMessage): ModelMessage;
+export declare function requestSmartCompaction(input: SmartCompactionInput | undefined, start: () => void): void;

package/dist/runtime/compaction/smart.js

@@ -0,0 +1,59 @@
+import { AgentError } from '../../error.js';
+import { compactSummaryFromCheckpoint } from '../../session/record-projection.js';
+export const SMART_COMPACTION_MARKER = '<mar_runtime>\n  <smart_compaction>For this message only, smart_compact may be considered at a clear transition into sustained new work, when the previous phase is largely complete and its details have low continuation value.</smart_compaction>\n</mar_runtime>';
+/** A measured watermark, not the stricter native-request budget calibration. */
+export function latestSmartContextTokens(records, modelId, contextWindowTokens) {
+    let tokens;
+    let matchingModel = false;
+    for (const record of records) {
+        const payload = record.payload;
+        if (compactSummaryFromCheckpoint(record) !== undefined) {
+            tokens = undefined;
+            // A sliced checkpoint does not prove the input window used by later usage.
+            matchingModel = false;
+        }
+        if (record.type === 'context.gc.completed')
+            tokens = undefined;
+        if (record.type === 'execution.header' && payload.mode !== 'compact') {
+            matchingModel =
+                payload.modelId === modelId && payload.contextWindowTokens === contextWindowTokens;
+            if (!matchingModel)
+                tokens = undefined;
+        }
+        if (matchingModel && payload.type === 'usage.updated' && payload.purpose !== 'compact') {
+            const value = payload.contextInputTokens ?? payload.inputTokens;
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                tokens = value;
+        }
+    }
+    return tokens;
+}
+/** Only provider views receive the marker; durable message content stays unchanged. */
+export function projectSmartCompactionMessage(message) {
+    if (message.role !== 'user' ||
+        message.contextKind !== undefined ||
+        !message.metadata?.smartCompaction)
+        return message;
+    const suffix = '\n\n' + SMART_COMPACTION_MARKER;
+    return {
+        ...message,
+        content: message.content + suffix,
+        ...(message.textBlocks ? { textBlocks: [...message.textBlocks, { text: suffix }] } : {})
+    };
+}
+export function requestSmartCompaction(input, start) {
+    if (!input?.eligible)
+        throw new AgentError('MAR_AGENT_SMART_COMPACT_DENIED', 'The current user input is not eligible for Smart Compaction.');
+    if ('error' in input)
+        throw input.error;
+    if (input.requested)
+        return;
+    input.requested = true;
+    try {
+        start();
+    }
+    catch (error) {
+        input.error = error;
+        throw error;
+    }
+}

package/dist/runtime/context/contextual-blocks.d.ts

@@ -0,0 +1,31 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import type { ModelContextualBlock, ModelTextBlock } from '../../model/contracts.js';
+import { type PromptPart } from '../../prompts/prompt-sections.js';
+export interface ContextualPart {
+    id: string;
+    source: ModelContextualBlock['source'];
+    authority: ModelContextualBlock['authority'];
+    content: string;
+    textBlocks?: readonly ModelTextBlock[];
+}
+export declare function contextualBlock(part: ContextualPart, kind: string, operation?: ModelContextualBlock['operation']): ModelContextualBlock;
+/** Keep arbitrary whole-string middleware and explicit cache scopes lossless. */
+export declare function splitContextualPrompt(composed: {
+    text: string;
+    blocks?: readonly ModelTextBlock[];
+    sections?: readonly PromptPart[];
+}): {
+    system: string;
+    systemBlocks?: readonly ModelTextBlock[];
+    parts: ContextualPart[];
+};
+interface ContextualChange {
+    part: ContextualPart;
+    block: ModelContextualBlock;
+    content: string;
+    textBlocks?: readonly ModelTextBlock[];
+}
+export declare function contextualChanges(previous: readonly ContextualPart[], current: readonly ContextualPart[]): ContextualChange[];
+/** Compact reuses a sent prefix when possible, but fallback evidence excludes private state. */
+export declare function projectCompactPromptMessages(messages: readonly ModelMessage[], parts: readonly ContextualPart[], previous: readonly ContextualPart[]): ModelMessage[];
+export {};

package/dist/runtime/context/contextual-blocks.js

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+import { resolveModelTextBlocks } from '../../model/text-blocks.js';
+import { renderPromptSections } from '../../prompts/prompt-sections.js';
+export function contextualBlock(part, kind, operation = 'replace') {
+    return {
+        id: part.id,
+        kind,
+        source: part.source,
+        authority: part.authority,
+        operation,
+        revision: createHash('sha256')
+            .update(JSON.stringify({
+            id: part.id,
+            source: part.source,
+            authority: part.authority,
+            content: part.content,
+            textBlocks: part.textBlocks,
+            operation
+        }))
+            .digest('hex')
+    };
+}
+const CORE_IDS = new Set([
+    'core:identity',
+    'core:instruction-priority',
+    'core:workspace-discipline',
+    'core:workflow',
+    'core:interaction',
+    'core:safety',
+    'core:output-style'
+]);
+const SDK_CONTEXTUAL_IDS = new Set([
+    'core:environment-rules',
+    'core:tools',
+    'core:long-running',
+    'core:mode',
+    'core:compaction',
+    'core:subagent',
+    'core:skill-catalog',
+    'core:child-instructions'
+]);
+/** Keep arbitrary whole-string middleware and explicit cache scopes lossless. */
+export function splitContextualPrompt(composed) {
+    const sections = composed.sections;
+    if (!sections ||
+        !sections.some((part) => CORE_IDS.has(part.id)) ||
+        composed.blocks !== undefined ||
+        renderPromptSections(sections) !== composed.text)
+        return {
+            system: composed.text,
+            ...(composed.blocks === undefined ? {} : { systemBlocks: composed.blocks }),
+            parts: []
+        };
+    let dynamicSeen = false;
+    for (const section of sections) {
+        if (!section.text)
+            continue;
+        if (!CORE_IDS.has(section.id))
+            dynamicSeen = true;
+        else if (dynamicSeen)
+            return { system: composed.text, parts: [] };
+    }
+    return {
+        system: renderPromptSections(sections.filter((part) => CORE_IDS.has(part.id))),
+        parts: sections.flatMap((section) => {
+            if (CORE_IDS.has(section.id) || !section.text)
+                return [];
+            return [
+                {
+                    id: section.id,
+                    source: section.id === 'core:caller-instructions'
+                        ? 'host'
+                        : SDK_CONTEXTUAL_IDS.has(section.id)
+                            ? 'sdk'
+                            : 'extension',
+                    authority: 'instruction',
+                    content: section.text
+                }
+            ];
+        })
+    };
+}
+export function contextualChanges(previous, current) {
+    const before = new Map(previous.map((part) => [part.id, part]));
+    const after = new Set(current.map((part) => part.id));
+    // A reorder changes instruction precedence even when each text is unchanged.
+    const retainedBefore = previous.filter((part) => after.has(part.id)).map((part) => part.id);
+    const appendedOrder = [
+        ...retainedBefore,
+        ...current.filter((part) => !before.has(part.id)).map((part) => part.id)
+    ];
+    const reordered = appendedOrder.some((id, index) => id !== current[index]?.id);
+    const changes = [];
+    for (const part of previous) {
+        if (after.has(part.id))
+            continue;
+        const { textBlocks: _blocks, ...retained } = part;
+        const removed = { ...retained, content: '' };
+        const block = contextualBlock(removed, 'instruction', 'remove');
+        changes.push({ part: removed, block, content: renderContextualChange(block, '') });
+    }
+    for (const part of current) {
+        const prior = before.get(part.id);
+        if (!reordered &&
+            prior &&
+            prior.source === part.source &&
+            prior.authority === part.authority &&
+            prior.content === part.content &&
+            (prior.textBlocks === part.textBlocks ||
+                (prior.textBlocks !== undefined &&
+                    part.textBlocks !== undefined &&
+                    prior.textBlocks.length === part.textBlocks.length &&
+                    prior.textBlocks.every((block, index) => {
+                        const next = part.textBlocks?.[index];
+                        return block.text === next?.text && block.cache === next?.cache;
+                    }))))
+            continue;
+        const block = contextualBlock(part, 'instruction');
+        const content = renderContextualChange(block, part.content);
+        changes.push({
+            part,
+            block,
+            content,
+            ...(part.textBlocks === undefined
+                ? {}
+                : {
+                    textBlocks: [
+                        { text: content.slice(0, content.length - part.content.length) },
+                        ...resolveModelTextBlocks(part.content, part.textBlocks)
+                    ]
+                })
+        });
+    }
+    return changes;
+}
+function renderContextualChange(block, content) {
+    const id = JSON.stringify(block.id);
+    const action = block.operation === 'remove'
+        ? `Remove only the previous contextual instruction block with id ${id}. Other instructions and user requests remain in effect.`
+        : `This is the current complete contextual instruction block with id ${id}. It replaces only earlier versions of the same block.`;
+    return `# Contextual instruction ${id}\n${action}\n${content}`;
+}
+/** Compact reuses a sent prefix when possible, but fallback evidence excludes private state. */
+export function projectCompactPromptMessages(messages, parts, previous) {
+    const baseline = messages.some((message) => message.contextualBlock?.authority === 'instruction')
+        ? previous
+        : [];
+    const additions = contextualChanges(baseline, parts).map(({ content, block, textBlocks }) => ({
+        role: 'user',
+        content,
+        contextKind: 'contextual',
+        contextualBlock: block,
+        ...(textBlocks === undefined ? {} : { textBlocks })
+    }));
+    const control = messages.findIndex((message) => message.contextKind === 'compact_control');
+    const index = control < 0 ? messages.length : control;
+    return [...messages.slice(0, index), ...additions, ...messages.slice(index)];
+}

package/dist/runtime/context/environment.d.ts

@@ -0,0 +1,5 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import type { EnvironmentContextState } from './contracts.js';
+export declare function restoreEnvironmentState(payload: unknown): EnvironmentContextState | undefined;
+export declare function environmentContextUpdate(current: EnvironmentContextState, previous?: EnvironmentContextState, contextualEntries?: readonly string[]): ModelMessage | undefined;
+export declare function currentLocalTimeContext(instant?: Date, timezone?: string): Pick<EnvironmentContextState, 'currentDate' | 'timezone'>;

package/dist/runtime/context/gc-candidates-code.d.ts

@@ -0,0 +1,6 @@
+import { type ContextGcPlannerInput, type ContextCandidate, type CandidateSavings, type ToolGroup } from './gc-contracts.js';
+export declare function collectCodeModeCandidates(input: ContextGcPlannerInput, groups: ReadonlyMap<string, ToolGroup>, existingTargets: ReadonlySet<string>, candidateSavings: CandidateSavings): {
+    eligible: ContextCandidate[];
+    protectedTokens: number;
+    retryAfterRollouts: number;
+};

package/dist/runtime/context/gc-candidates-code.js

@@ -0,0 +1,102 @@
+import { retainedCodeInputs } from '../../session/context-gc-observations.js';
+import { contextGcTargetKey } from '../../session/context-gc-checkpoint.js';
+import { codeCellCompletionSequence, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, normalizeContextGcCodeModeInput } from '../../session/context-gc-replacements.js';
+import { CONTEXT_GC_POLICY } from './gc-economics.js';
+import { successfulRolloutsAfter, targetFor, isRecord } from './gc-candidates.js';
+export function collectCodeModeCandidates(input, groups, existingTargets, candidateSavings) {
+    const eligible = [];
+    let protectedTokens = 0;
+    let retryAfterRollouts = Infinity;
+    for (const group of [...groups.values()].filter((item) => ['code_exec', 'code_exec_wait'].includes(item.toolName))) {
+        if (!group.call ||
+            !group.result ||
+            group.failed ||
+            !group.completed ||
+            group.call.message.role !== 'tool_call' ||
+            group.result.message.role !== 'tool' ||
+            typeof group.result.message.content !== 'string')
+            continue;
+        const code = normalizeContextGcCodeModeInput(group.call.message.arguments);
+        const completedPayload = group.completed.payload;
+        const completionSequence = codeCellCompletionSequence(input.records, group.completed);
+        if ((group.toolName !== 'code_exec_wait' && !code) ||
+            completionSequence === undefined ||
+            !isRecord(completedPayload) ||
+            typeof completedPayload.truncated !== 'boolean')
+            continue;
+        for (const observation of group.result.message.observations ?? []) {
+            if (observation.type !== 'value')
+                continue;
+            const target = targetFor(group.result.record, {
+                ...group.result.message,
+                observationId: observation.id
+            });
+            if (!target || existingTargets.has(contextGcTargetKey(target)))
+                continue;
+            const evidenceSequence = group.result.record.sequence;
+            const candidate = {
+                replacements: [
+                    {
+                        kind: 'CODE_MODE_OUTPUT',
+                        callId: group.callId,
+                        target,
+                        replacementContent: contextGcCodeModeOutputReplacement(observation.value, observation.truncated === true),
+                        evidenceSequence
+                    }
+                ],
+                observedRollouts: successfulRolloutsAfter(input.records, Math.max(evidenceSequence, completionSequence), input.modelId, input.contextWindowTokens),
+                evidenceSequence
+            };
+            const reclaimedTokens = candidateSavings(candidate);
+            if (reclaimedTokens <= 0)
+                continue;
+            if (candidate.observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts)
+                eligible.push(candidate);
+            else {
+                protectedTokens += reclaimedTokens;
+                retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.largeExecProtectionRollouts - candidate.observedRollouts);
+            }
+        }
+        const callTarget = targetFor(group.call.record, group.call.message);
+        const resultTarget = targetFor(group.result.record, group.result.message);
+        if (!callTarget || !resultTarget)
+            continue;
+        const evidenceSequence = group.result.record.sequence;
+        const replacements = [];
+        if (code && !existingTargets.has(contextGcTargetKey(callTarget)))
+            replacements.push({
+                kind: 'TOOL_CALL_INPUT',
+                toolName: group.toolName,
+                callId: group.callId,
+                target: callTarget,
+                replacementArguments: contextGcCodeModeInputReplacement(code, group.result.message.observations ? retainedCodeInputs(input.records, group.callId) : []),
+                providerAliasTargets: group.aliases
+                    .map(({ record, message }) => targetFor(record, message))
+                    .filter((target) => target !== undefined),
+                evidenceSequence
+            });
+        if (!group.result.message.observations &&
+            !existingTargets.has(contextGcTargetKey(resultTarget)))
+            replacements.push({
+                kind: 'CODE_MODE_OUTPUT',
+                callId: group.callId,
+                target: resultTarget,
+                replacementContent: contextGcCodeModeOutputReplacement(group.result.message.content, completedPayload.truncated),
+                evidenceSequence
+            });
+        if (replacements.length === 0)
+            continue;
+        const observedRollouts = successfulRolloutsAfter(input.records, Math.max(evidenceSequence, completionSequence), input.modelId, input.contextWindowTokens);
+        const candidate = { replacements, observedRollouts, evidenceSequence };
+        const reclaimedTokens = candidateSavings(candidate);
+        if (reclaimedTokens <= 0)
+            continue;
+        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts)
+            eligible.push(candidate);
+        else {
+            protectedTokens += reclaimedTokens;
+            retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.largeExecProtectionRollouts - observedRollouts);
+        }
+    }
+    return { eligible, protectedTokens, retryAfterRollouts };
+}

package/dist/runtime/context/gc-candidates-exec.d.ts

@@ -0,0 +1,6 @@
+import { type ContextGcPlannerInput, type ContextCandidate, type CandidateSavings, type ToolGroup } from './gc-contracts.js';
+export declare function collectExecCandidates(input: ContextGcPlannerInput, groups: ReadonlyMap<string, ToolGroup>, existingTargets: ReadonlySet<string>, candidateSavings: CandidateSavings): {
+    eligible: ContextCandidate[];
+    protectedTokens: number;
+    retryAfterRollouts: number;
+};