@sema-agent/core 1.279.0

package/dist/core/types.d.ts

@@ -0,0 +1,684 @@
+import type { TSchema } from "typebox";
+import type { AgentTool, ThinkingLevel } from "../internal/harness.js";
+import type { DocumentContent, ImageContent, Model, ResilienceOptions, StreamFn, TextContent } from "../internal/llm.js";
+import type { TaskNotificationPayload } from "./task-notification.js";
+export type ModelRef = string | Model;
+export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier" | "classifier";
+export type RoleSpec = ModelRef | {
+    model?: ModelRef;
+    select?: import("./select-model.js").ModelCriteria;
+    thinking?: ThinkingLevel;
+    systemPrompt?: string;
+};
+export type ModelRoles = Partial<Record<ModelRole, RoleSpec>>;
+export interface Brain {
+    stream: StreamFn;
+    complete?: (model: Model, context: {
+        systemPrompt?: string;
+        messages: unknown[];
+    }, options?: unknown) => Promise<unknown>;
+}
+export type ToolEffect = "read" | "write" | "idempotent";
+export interface ToolSpec<TParams extends TSchema = TSchema> {
+    name: string;
+    aliases?: string[];
+    description: string;
+    label?: string;
+    agentListing?: ReadonlyArray<{
+        name: string;
+        description: string;
+    }>;
+    prepareArguments?: (args: unknown) => unknown;
+    effect?: ToolEffect;
+    egress?: true;
+    irreversibility?: "never" | "maybe" | "always";
+    reversibilityProbe?: (args: unknown) => {
+        reversible: boolean;
+    } | Promise<{
+        reversible: boolean;
+    }>;
+    executionMode?: "sequential" | "parallel";
+    isConcurrencySafe?: (args: unknown) => boolean;
+    parameters: TParams;
+    offload?: boolean;
+    offloadThresholdChars?: number;
+    defer?: boolean;
+    execute: (args: unknown, ctx: ToolExecuteContext) => Promise<ToolReturn> | ToolReturn;
+}
+export type ToolReturn = string | {
+    content: Array<TextContent | ImageContent | DocumentContent> | string;
+    details?: unknown;
+    terminate?: boolean;
+};
+export interface ToolExecuteContext {
+    toolCallId: string;
+    signal?: AbortSignal;
+    parentCwd?: string;
+    reportUsage?: (usage: {
+        tokens: number;
+        turns: number;
+        tasks: number;
+        costUsd?: number;
+        costMicroUsd?: number;
+    }) => void;
+    model?: Model;
+    thinkingLevel?: ThinkingLevel;
+    principal?: string;
+    clientContext?: TaskSpec["clientContext"];
+    activeSkillScope?: () => readonly unknown[];
+    taskId?: string;
+    sessionId?: string;
+    backgroundScope?: "task" | "session";
+    onBackgroundChildEvent?: (event: BackgroundChildEvent) => void;
+    onTaskNotification?: (n: import("./task-notification.js").TaskNotificationPayload, opts?: {
+        priority?: import("./task-notification.js").SystemInjectionPriority;
+    }) => void;
+    forwardEvent?: (event: TaskEvent) => void;
+    onSubagentSpawn?: (handle: import("../agents/subagent.js").SubagentSteerHandle) => void;
+    subagentRetain?: import("../agents/subagent.js").SubagentRetainLedger;
+    worktreeIsolation?: import("../agents/subagent.js").SubagentWorktreeIsolation;
+    insideFork?: boolean;
+    observersAllowed?: true;
+    forkAccess?: {
+        denied: "task" | "principal";
+    };
+    requestReview?: (opts?: {
+        reason?: string;
+    }) => void;
+    requestStopAfterTurn?: () => void;
+    enterPlanMode?: () => void;
+}
+export interface BeforeWriteRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    path: string;
+    key: string;
+    content: string;
+}
+export type BeforeWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type BeforeWriteHook = (req: BeforeWriteRequest) => BeforeWriteResult | undefined | Promise<BeforeWriteResult | undefined>;
+export interface HandsBandOptions {
+    bashReadonlyAllow?: readonly string[];
+    commitCoAuthor?: string | false;
+    readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
+    beforeWrite?: BeforeWriteHook;
+}
+export interface AgentDefinition {
+    name: string;
+    whenToUse?: string;
+    whenToUseLean?: string;
+    allowTools?: string[];
+    denyTools?: string[];
+    skills?: SkillSpec[];
+    background?: boolean;
+    isolation?: "worktree";
+    model?: ModelRef;
+    thinking?: ThinkingLevel;
+    systemPrompt?: string;
+    maxTurns?: number;
+    memory?: TaskSpec["memory"];
+    observer?: string;
+    observerMessage?: string;
+}
+export interface McpServerSpec {
+    name: string;
+    transport: {
+        kind: "stdio";
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    } | {
+        kind: "http";
+        url: string;
+        headers?: Record<string, string>;
+        principalHeader?: string;
+    };
+    allowTools?: string[];
+    elicitation?: boolean;
+    toolAxes?: Record<string, {
+        effect?: ToolEffect;
+        egress?: boolean;
+        irreversibility?: "always" | "never";
+    }>;
+}
+export interface McpElicitRequest {
+    server: string;
+    message: string;
+    requestedSchema?: unknown;
+    url?: string;
+    principal?: string;
+}
+export interface McpElicitResponse {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]>;
+}
+export type OnElicit = (req: McpElicitRequest, signal?: AbortSignal) => Promise<McpElicitResponse>;
+export interface SkillManifest {
+    allowTools: string[];
+    allowPaths?: string[];
+    egress?: boolean;
+    lineageId: string;
+}
+export interface SkillSpec {
+    name: string;
+    description: string;
+    content: string;
+    manifest?: SkillManifest;
+}
+export type ImageInput = {
+    data: string;
+    mimeType: string;
+} | {
+    url: string;
+};
+export interface TaskSpec {
+    taskId?: string;
+    objective: string;
+    principal?: string;
+    images?: ImageInput[];
+    sessionId?: string;
+    requireExistingSession?: boolean;
+    clientContext?: {
+        timeZone?: string;
+        userEmail?: string;
+    };
+    resumeAt?: string;
+    model?: ModelRef;
+    modelRole?: ModelRole;
+    roles?: ModelRoles;
+    compactionModel?: ModelRef;
+    thinking?: ThinkingLevel;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    promptProvider?: import("../prompts/default.js").PromptProvider;
+    memory?: import("./memory.js").MemorySpecInput;
+    memoryConsolidation?: MemoryConsolidationConfig;
+    suggestNextPrompts?: boolean | {
+        count?: number;
+        role?: ModelRole;
+    };
+    rewindFiles?: boolean;
+    rewindFilesTo?: string;
+    tools?: ToolSpec[];
+    toolPolicy?: import("./tool-policy.js").ToolPolicy;
+    onAsk?: import("./tool-policy.js").OnAsk;
+    onQuestion?: import("./ask-question.js").OnQuestion;
+    lspManager?: import("./lsp.js").LspServerManager;
+    lspDiagnostics?: boolean;
+    hooks?: import("./hooks.js").Hooks;
+    durableApproval?: {
+        scope: string;
+        ttlMs?: number;
+    };
+    resourceSuspend?: {
+        scope: string;
+        totalBudgetUsd?: number;
+        maxSlices?: number;
+        ttlMs?: number;
+    };
+    preemptSignal?: AbortSignal;
+    resilience?: ResilienceOptions;
+    finalVerification?: boolean;
+    maxSuspends?: number;
+    checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
+    handsReadOnly?: boolean;
+    additionalDirectories?: string[];
+    enablePlanMode?: boolean;
+    enableFork?: boolean;
+    shellGate?: "off" | "always" | "classify";
+    mcp?: McpServerSpec[];
+    skills?: SkillSpec[];
+    backgroundScope?: "task" | "session";
+    envFacts?: {
+        profile?: string;
+        capabilities?: readonly string[];
+        pkgSource?: string;
+        egress?: "none" | "allowlist" | "full";
+        scratchpadDir?: string;
+    };
+    limits?: {
+        maxTurns?: number;
+        timeoutSec?: number;
+        maxOutputTokens?: number;
+        deadlineNudge?: false | {
+            at?: [number, number];
+        };
+        callCapByDeadline?: false;
+        gracefulFinalize?: false;
+    };
+    forwardSubagentEvents?: boolean;
+    retainSubagentSessions?: boolean | {
+        ttlMs?: number;
+        max?: number;
+    };
+    streamingToolExecution?: boolean;
+    maxCostUsd?: number;
+    maxTokens?: number;
+    budgetStreamCancel?: boolean;
+    degrade?: {
+        to: ModelRef;
+        atCostFraction: number;
+    };
+    outputSchema?: TSchema;
+    outputRetries?: number;
+    tracer?: import("./trace.js").TracerHook;
+    toolResultThresholdChars?: number;
+    compaction?: {
+        enabled?: boolean;
+        withinTask?: boolean;
+        reserveTokens?: number;
+        keepRecentTokens?: number;
+        instructions?: string;
+        attachWorkingFiles?: boolean | {
+            maxFiles?: number;
+            maxCharsPerFile?: number;
+        };
+    };
+    attachments?: {
+        todoReminder?: true;
+        todoReminderMode?: "baseline" | "off";
+        changedFiles?: true | {
+            maxFiles?: number;
+        };
+        planModeReminder?: true;
+        budgetUsd?: true;
+        backgroundTasks?: true;
+        toolsDelta?: true;
+        agentListing?: true;
+        mcpInstructions?: true;
+    };
+    enableBlockedReport?: boolean;
+    selfOrchestration?: boolean;
+    getApiKeyAndHeaders?: (model: Model) => Promise<{
+        apiKey: string;
+        headers?: Record<string, string>;
+    } | undefined>;
+    signal?: AbortSignal;
+}
+export type TaskStatus = "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review";
+export interface TaskResult {
+    taskId: string;
+    sessionId: string;
+    status: TaskStatus;
+    model?: string;
+    result: string;
+    salvagedOutput?: string;
+    blockedReason?: string;
+    checkpointToken?: import("./checkpoint-store.js").CheckpointToken;
+    checkpointGate?: import("./checkpoint-store.js").CheckpointGate;
+    errorMessage?: string;
+    errorCode?: string;
+    degraded?: {
+        from: string;
+        to: string;
+        reason: "breaker_open" | "rate_limit" | "budget" | "server_error" | "last_resort";
+        chain?: string[];
+        atTurn: number;
+    };
+    structuredOutput?: unknown;
+    stats: {
+        turns: number;
+        tokens: number;
+        toolCalls?: number;
+        promptTokens?: number;
+        cachedTokens?: number;
+        cacheWriteTokens?: number;
+        cacheHitRate?: number;
+        totalInputTokens?: number;
+        outputTokens?: number;
+        cacheWriteTokensLong?: number;
+        costMicroUsd?: number;
+        costUsd?: number;
+        nested?: {
+            tokens: number;
+            turns: number;
+            tasks: number;
+            costUsd?: number;
+            costMicroUsd?: number;
+        };
+        memory?: {
+            tokens: number;
+            costMicroUsd: number;
+            applied: number;
+        };
+        suggestions?: {
+            tokens: number;
+            costMicroUsd: number;
+        };
+        mechanisms?: {
+            finalizeInjected?: true;
+            nudgesSent?: number;
+            capShrinks?: number;
+            callCutoffs?: number;
+            toolClamps?: number;
+            finalVerifyInjected?: true;
+            finalVerifyInjections?: number;
+            attachmentsInjected?: number;
+            repetitionCuts?: number;
+            repetitionSpared?: number;
+            repetitionEvents?: Array<{
+                turn: number;
+                action: "cut" | "spared";
+                rule: "char-run" | "unit-loop";
+                period: number;
+                reps: number;
+                segment: string;
+            }>;
+        };
+        humanReview?: {
+            count: number;
+            totalWaitMs: number;
+            gates: Array<{
+                kind: string;
+                waitMs: number;
+                decision?: string;
+                toolName?: string;
+                toolArg?: string;
+            }>;
+        };
+        costBreakdown?: {
+            llmRootMicroUsd: number;
+            nestedSubagentMicroUsd: number;
+            memoryConsolidationMicroUsd: number;
+            suggestionsMicroUsd?: number;
+            compactionMicroUsd: number;
+        };
+    };
+}
+export interface TaskEventIdentity {
+    eventId?: string;
+    parentToolCallId?: string;
+    sourceTaskId?: string;
+}
+export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open";
+export interface BrainStatus {
+    phase: BrainStatusPhase;
+    detail?: string;
+    retryInSec?: number;
+}
+export interface ToolActivity {
+    phase: "start" | "end";
+    toolCallId: string;
+    toolName: string;
+    arg?: string;
+    isError?: boolean;
+}
+export type TaskEvent = ({
+    type: "text_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    type: "reasoning_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    type: "tool_start";
+    toolCallId: string;
+    toolName: string;
+    label?: string;
+    args: unknown;
+} & TaskEventIdentity) | ({
+    type: "tool_end";
+    toolCallId: string;
+    toolName: string;
+    label?: string;
+    isError: boolean;
+    output?: unknown;
+    structured?: unknown;
+    truncated?: boolean;
+} & TaskEventIdentity) | ({
+    type: "turn_end";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        costMicroUsd: number;
+    };
+    usageMissing?: true;
+    stopReason?: string;
+} & TaskEventIdentity) | {
+    type: "compacted";
+    trigger: "auto" | "manual";
+    tokensBefore: number;
+    tokensAfter?: number;
+    triggerTokensBefore?: number;
+    durationMs?: number;
+    preserved_segment?: {
+        firstKeptEntryId: string;
+    };
+    attachedFiles?: Array<{
+        path: string;
+        chars: number;
+        truncated: boolean;
+    }>;
+} | ({
+    type: "steering_injected";
+    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "changed_files" | "plan_mode" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "mcp_instructions";
+    preview: string;
+} & TaskEventIdentity) | ({
+    type: "diagnostics";
+    files: Array<{
+        uri: string;
+        diagnostics: Array<{
+            message: string;
+            severity?: number;
+            range?: {
+                start: {
+                    line: number;
+                    character: number;
+                };
+                end?: {
+                    line: number;
+                    character: number;
+                };
+            };
+            code?: string | number;
+            source?: string;
+        }>;
+    }>;
+    isNew: true;
+} & TaskEventIdentity) | ({
+    type: "message_committed";
+    entryId: string;
+    role: "user" | "assistant" | "toolResult";
+    toolCallId?: string;
+} & TaskEventIdentity) | ({
+    type: "status";
+} & BrainStatus & TaskEventIdentity) | ({
+    type: "task_notification";
+    notification: TaskNotificationPayload;
+} & TaskEventIdentity) | ({
+    type: "task_progress";
+    taskId: string;
+    parentTaskId?: string;
+    name?: string;
+    currentAction?: string;
+    usage: {
+        totalTokens: number;
+        toolUses: number;
+        durationMs: number;
+    };
+    status: "running";
+} & TaskEventIdentity) | ({
+    type: "workspace_changed";
+    cwd: string;
+} & TaskEventIdentity) | {
+    type: "done";
+    result: TaskResult;
+};
+export type CompactOutcome = "compacted" | "failed" | "mooted" | "noop" | "blocked" | "disabled";
+export interface TaskStream extends AsyncIterable<TaskEvent> {
+    result(): Promise<TaskResult>;
+    consolidation(): Promise<void>;
+    suggestions(): Promise<string[]>;
+    steer(text: string, options?: {
+        trusted?: boolean;
+    }): Promise<void>;
+    compact(): Promise<CompactOutcome>;
+    detach(toolCallId: string): void;
+    interrupt(): Promise<void>;
+    destroy(): Promise<void>;
+}
+export interface MemoryConsolidationConfig {
+    enabled: boolean;
+    role?: ModelRole;
+    band?: {
+        lo: number;
+        hi: number;
+    };
+    searchLimit?: number;
+    maxNotesPerTask?: number;
+    timeoutSec?: number;
+}
+export interface WorkflowGovernanceBaseline {
+    base: Partial<TaskSpec>;
+    workflowModelAllowlist?: string[];
+}
+export interface RuntimeCaps {
+    allowWorkflows?: boolean;
+    allowFork?: boolean;
+    allowObservers?: boolean;
+    forceDurableGate?: boolean;
+    autoMode?: boolean;
+}
+export interface BackgroundChildEvent {
+    kind: "spawn" | "tick" | "terminal";
+    taskId: string;
+    sessionScoped: boolean;
+    owner?: string;
+    scope?: string;
+    description?: string;
+    parentTaskId?: string;
+    progressTaskId?: string;
+    progressParentTaskId?: string;
+    name?: string;
+    currentAction?: string;
+    sessionId?: string;
+    transcriptId?: string;
+    recentSteps?: import("../agents/subagent-steps.js").SubagentStep[];
+    editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
+    resumable?: boolean;
+    status?: "completed" | "killed" | "failed";
+    stoppedBy?: "user" | "parent" | "system" | (string & {});
+    summary?: string;
+    usage?: {
+        totalTokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+        tokens?: number;
+        turns?: number;
+        costMicroUsd?: number;
+    };
+}
+export interface ProjectMemoryLoad {
+    content: string | null;
+    seededFiles?: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface RunnerDeps {
+    brain: Brain;
+    models?: Record<string, Model>;
+    tiers?: Record<string, ModelRef>;
+    agents?: AgentDefinition[];
+    builtinAgents?: boolean;
+    hands?: HandsBandOptions;
+    modelKnowledgeCutoffs?: Record<string, string>;
+    roles?: ModelRoles;
+    sessionStore?: import("./session.js").SessionStore;
+    checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
+    fileSnapshotStore?: import("./file-snapshot-store.js").FileSnapshotStore;
+    sessionPolicyStore?: import("./session-policy-store.js").SessionPolicyStore;
+    runtimeCapsResolver?: (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
+    autoMode?: {
+        rules?: import("./auto-mode-prompt.js").AutoModeRules;
+        settingsDenyRules?: readonly string[];
+        sessionContext?: readonly string[];
+        window?: import("./auto-mode-prompt.js").AutoModeWindowOptions;
+        timeoutMs?: number;
+        failureThreshold?: number;
+        onBreakerOpen?: (info: {
+            consecutiveFailures: number;
+            lastCause: string;
+        }) => void;
+    };
+    onBackgroundChildEvent?: (event: BackgroundChildEvent) => void;
+    workflowScriptRunner?: import("../orchestration/workflow-script-runner.js").WorkflowScriptRunner;
+    workflowGovernanceBaseline?: WorkflowGovernanceBaseline;
+    workflowLimits?: import("../orchestration/run-workflow-tool.js").WorkflowLimits;
+    workflowCompletionNotifier?: import("../orchestration/run-workflow-tool.js").WorkflowCompletionNotifier;
+    workflowRunStore?: import("./workflow-run-store.js").WorkflowRunStore;
+    workflowJournalStore?: import("./workflow-journal-store.js").WorkflowJournalStore;
+    workflowScriptStore?: import("../orchestration/workflow-script-store.js").WorkflowScriptStore;
+    builtinWorkflows?: boolean;
+    onWorkflowAgentSpawn?: (handle: import("../orchestration/workflow.js").WorkflowAgentHandle) => void;
+    maxSuspends?: number;
+    now?: () => number;
+    memoryStore?: import("./memory.js").MemoryStore;
+    memoryBackend?: import("./memory-engine/types.js").MemoryBackend;
+    memoryEngineDir?: string;
+    onMemoryHarvestReport?: (report: import("./memory-engine/types.js").HarvestReport, info: {
+        sessionId: string;
+        phase: "checkpoint" | "terminal";
+    }) => void;
+    loadProjectMemory?: (ctx: {
+        cwd: string;
+        handsEnabled: boolean;
+        isSubagent: boolean;
+        agentName?: string;
+    }) => Promise<string | null | ProjectMemoryLoad> | string | null | ProjectMemoryLoad;
+    utilityGate?: import("./memory.js").UtilityGate;
+    memoryConsolidation?: MemoryConsolidationConfig;
+    memoryRecall?: {
+        enabled?: boolean;
+        thresholdBytes?: number;
+        select?: import("./memory-recall.js").MemorySelector;
+        selectorModel?: ModelRef;
+        maxSelected?: number;
+        maxLinked?: number;
+        timeoutMs?: number;
+    };
+    promptProvider?: import("../prompts/default.js").PromptProvider;
+    onElicit?: OnElicit;
+    mcpImageResizer?: import("./mcp.js").McpImageResizer;
+    toolPolicy?: import("./tool-policy.js").ToolPolicy;
+    onAsk?: import("./tool-policy.js").OnAsk;
+    onQuestion?: import("./ask-question.js").OnQuestion;
+    lspManager?: import("./lsp.js").LspServerManager;
+    hooks?: import("./hooks.js").Hooks;
+    allowImageUrl?: (url: string) => boolean;
+    onError?: (err: unknown, context: {
+        phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
+        sessionId: string;
+        classification?: string;
+    }) => void;
+    tracer?: import("./trace.js").TracerHook;
+    onTaskOutcome?: (outcome: import("./task-outcome.js").TaskOutcome) => void;
+    pricing?: Record<string, import("./pricing.js").ModelPricing>;
+    executionEnv?: import("../internal/harness.js").ExecutionEnv;
+    executionEnvFactory?: import("./remote-env.js").ExecutionEnvFactory;
+    graderEnvFactory?: import("./remote-env.js").ExecutionEnvFactory;
+    rootPath?: string;
+    toolResultStore?: import("./tool-result-store.js").ToolResultStore;
+    toolResultThresholdChars?: number;
+    cacheBreakDetection?: boolean;
+    mediaByteCapBytes?: number;
+    onMediaStripped?: (info: {
+        totalBytes: number;
+        limitBytes: number;
+        removedCount: number;
+        removedBytes: number;
+    }) => void;
+    deferMode?: "auto";
+    summaryProvider?: import("./auto-compaction.js").MaybeCompactOptions["summaryProvider"];
+    onCompaction?: import("./auto-compaction.js").MaybeCompactOptions["onCompaction"];
+    maxConsecutiveProviderReuse?: number;
+    dynamicRecall?: import("./dynamic-recall.js").DynamicRecallConfig;
+}
+export type { AgentTool, Model, StreamFn, ThinkingLevel };
+//# sourceMappingURL=types.d.ts.map