@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/lib/context-window.js

@@ -1,10 +1,13 @@
-import { TOOL_CONTINUATION_NUDGE } from './capabilities/tool-turns.js';
 export const TOOL_RESULT_TRUNCATION_MARKER = '\n[tool result truncated for context]\n';
-function isTurnBoundary(message) {
-    return message.role === 'user' && message.content !== TOOL_CONTINUATION_NUDGE;
+const TOOL_SEARCH_RESULT = '{"tool_search":';
+const compactedSources = new WeakMap();
+export function compactedFrom(message) {
+    return compactedSources.get(message);
 }
-export function contextCandidates(history) {
-    const { prefix, turns } = splitTurns(history);
+export function contextCandidates(history, ...nudges) {
+    const isBoundary = (message) => message.role === 'user' &&
+        !nudges.some((nudge) => message.content === nudge || message.content.startsWith(`${nudge}\nPlan:\n`));
+    const { prefix, turns } = splitTurns(history, isBoundary);
     if (!turns.length) {
         return [{ history, droppedTurns: 0 }];
     }
@@ -13,18 +16,18 @@ export function contextCandidates(history) {
         history: droppedTurns ? [...prefix, ...turns.slice(droppedTurns).flat()] : history,
         droppedTurns
     }));
-    appendToolCompactions(candidates);
+    appendToolCompactions(candidates, isBoundary);
     return candidates;
 }
-function splitTurns(history) {
-    const firstUser = history.findIndex(isTurnBoundary);
+function splitTurns(history, isBoundary) {
+    const firstUser = history.findIndex(isBoundary);
     if (firstUser === -1) {
         return { prefix: history, turns: [] };
     }
     const prefix = history.slice(0, firstUser);
     const starts = [];
     for (const [i, message] of history.entries()) {
-        if (i >= firstUser && isTurnBoundary(message)) {
+        if (i >= firstUser && isBoundary(message)) {
             starts.push(i);
         }
     }
@@ -44,12 +47,12 @@ function dropCounts(max) {
     }
     return counts;
 }
-function appendToolCompactions(candidates) {
+function appendToolCompactions(candidates, isBoundary) {
     const last = candidates[candidates.length - 1];
     if (!last) {
         return;
     }
-    const tools = compactableTools(last.history);
+    const tools = compactableTools(last.history, isBoundary);
     let history = last.history;
     while (true) {
         const selected = longestTool(tools);
@@ -61,8 +64,8 @@ function appendToolCompactions(candidates) {
         candidates.push({ history, droppedTurns: last.droppedTurns });
     }
 }
-function compactableTools(history) {
-    const newestUser = history.findLastIndex(isTurnBoundary);
+function compactableTools(history, isBoundary) {
+    const newestUser = history.findLastIndex(isBoundary);
     if (newestUser === -1) {
         return [];
     }
@@ -72,7 +75,10 @@ function compactableTools(history) {
             continue;
         if (message.content.length <= TOOL_RESULT_TRUNCATION_MARKER.length)
             continue;
-        tools.push({ index, original: message.content, target: message.content.length });
+        if (message.content.startsWith(TOOL_SEARCH_RESULT)) {
+            continue;
+        }
+        tools.push({ index, source: message, target: message.content.length });
     }
     return tools;
 }
@@ -81,7 +87,7 @@ function longestTool(tools) {
         .filter((tool) => tool.target > TOOL_RESULT_TRUNCATION_MARKER.length)
         .sort((a, b) => b.target - a.target)[0];
 }
-function compactContent(content, target) {
+export function compactContent(content, target) {
     const retained = target - TOOL_RESULT_TRUNCATION_MARKER.length;
     const head = Math.ceil(retained / 2);
     const tail = Math.floor(retained / 2);
@@ -90,5 +96,10 @@ function compactContent(content, target) {
 function compactTool(selected, message, index) {
     if (index !== selected.index)
         return message;
-    return { ...message, content: compactContent(selected.original, selected.target) };
+    const compacted = {
+        ...message,
+        content: compactContent(selected.source.content, selected.target)
+    };
+    compactedSources.set(compacted, selected.source);
+    return compacted;
 }

package/dist-lib/lib/contract/agent.d.ts

@@ -0,0 +1,65 @@
+import type { LlmGenerationParams } from '../models/llm-presets.ts';
+import type { DriveRoot } from '../tools/fs/scope.ts';
+import type { CliValidator } from '../tools/skills/cli-schema-types.ts';
+import type { AgentConfig, ResponseFormat, ToolDefinition } from './completion.ts';
+import type { Message } from './run.ts';
+export type { LlmGenerationParams };
+export interface AgentSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly tools: readonly string[];
+    readonly cliValidator?: CliValidator;
+}
+export interface SystemPromptParts {
+    text: string;
+    bioChars: number;
+    skillsChars: number;
+}
+export interface SkillActivation {
+    skillsSelected: boolean;
+    enabledSkills: ReadonlyArray<string>;
+    mention: string | null;
+    loadedSkills: ReadonlySet<string>;
+}
+export interface AgentPolicy {
+    readonly sandbox: boolean;
+    readonly skipApprovals: boolean;
+}
+export interface AgentPorts<Skill extends AgentSkill = AgentSkill> {
+    generationParams(model: string | undefined, reasoning: boolean | undefined, thinking: boolean | undefined): LlmGenerationParams | undefined;
+    systemPrompt(input: {
+        bio: string | null | undefined;
+        toolNames: readonly string[];
+        skills: readonly Skill[];
+    }): SystemPromptParts;
+    mention(messages: readonly Message[], skills: readonly Skill[]): Skill | null;
+    implicitSkill(messages: readonly Message[], skills: readonly Skill[]): Skill | null;
+}
+export interface AgentRequest<Skill extends AgentSkill = AgentSkill> {
+    readonly agent: AgentConfig | undefined;
+    readonly model: string | undefined;
+    readonly thinkingDefault?: string | undefined;
+    readonly generationParams?: LlmGenerationParams | undefined;
+    readonly responseFormat?: ResponseFormat | undefined;
+    readonly messages: readonly Message[];
+    readonly tools: readonly ToolDefinition[];
+    readonly skills: readonly Skill[];
+    readonly loadedSkills: ReadonlySet<string>;
+    readonly fsRoots: readonly DriveRoot[];
+    readonly fsWriteRoots: readonly DriveRoot[];
+    readonly planning?: boolean;
+    readonly planMode?: boolean;
+}
+export interface ResolvedAgent<Skill extends AgentSkill = AgentSkill> {
+    readonly enabled: ToolDefinition[];
+    readonly system: SystemPromptParts;
+    readonly activation: SkillActivation;
+    readonly activeSkills: Skill[];
+    readonly mention: Skill | null;
+    readonly preload: Skill | null;
+    readonly grantedOps: Map<string, CliValidator[]>;
+    readonly writableRoots: DriveRoot[];
+    readonly generationParams: LlmGenerationParams | undefined;
+    readonly policy: AgentPolicy;
+    select(loadedSkills: ReadonlySet<string>): ToolDefinition[];
+}

package/dist-lib/lib/{capabilities/types.d.ts → contract/completion.d.ts}

@@ -1,15 +1,27 @@
-import type { CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
+import type { CompletionFinal, Tool as SdkTool, ToolCallWithCall, ToolDialect } from '@qvac/sdk';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { TextEvent } from '../helpers/thinking.ts';
 import type { LlmGenerationParams } from '../models/llm-presets.ts';
+import type { CapabilityProfile } from '../models/model-catalog-constants.ts';
 import type { DriveRoot } from '../tools/fs/scope.ts';
-import type { CliValidator } from '../tools/skills/cli-schema.ts';
-import type { Toolset } from '../tools/toolsets.ts';
-import type { ToolCallDisplay } from '../tool-call-display.ts';
-import type { UsageBreakdown } from './usage-breakdown.ts';
-import type { Message, ResourceDescriptor, RunBackendUse, RunBudget, RunLifecycleEvent, ToolActivityEvent, ToolDecision, ToolEffect } from '../machine/index.ts';
-export type { Message, ResourceDescriptor, RunBackendUse, RunBudget, RunLifecycleEvent, ToolActivityEvent, ToolDecision, ToolEffect };
-export interface Agent {
+import type { CliValidator } from '../tools/skills/cli-schema-types.ts';
+import type { UsageBreakdown } from '../capabilities/usage-breakdown.ts';
+import type { KnowledgeGrant } from './knowledge.ts';
+import type { GoalStatus, HookRejection, Message, ResourceDescriptor, RoundSpeed, RunBackendUse, RunBudget, RunLifecycleEvent, ToolActivityEvent, ToolCallDisplay, ToolDecision, ToolEffect, ToolSpeed, TrustedSource, TrustedSourceFacts } from './run.ts';
+export type { CliValidator, DriveRoot, LlmGenerationParams };
+export interface OutboundGuard {
+    facts(origin: TrustedSourceFacts['origin'], text: string): TrustedSourceFacts;
+    check(toolName: string, args: Record<string, unknown>, options: {
+        readonly sources: readonly TrustedSource[];
+        readonly sourceFacts?: readonly TrustedSourceFacts[];
+        readonly externalWrite?: boolean;
+    }): string | null;
+}
+export interface AgentHandoff {
+    id: string;
+    description: string;
+}
+export interface AgentConfig {
     id?: string;
     name?: string;
     bio?: string;
@@ -28,6 +40,9 @@ export interface Agent {
     approvalMode?: 'ask' | 'skip-all' | null;
     disabledToolsets?: string[] | null;
     sandboxMode?: boolean | null;
+    handoffs?: AgentHandoff[] | null;
+    plan?: boolean | null;
+    model?: string | null;
 }
 export interface ImageSettings {
     modelChoice?: string;
@@ -49,6 +64,7 @@ export type ApproveFn = (call: {
     effect?: ToolEffect;
     intent?: string | null;
     display?: ToolCallDisplay | null;
+    quote?: string | null;
 }) => Promise<boolean>;
 export type ToolActivityFn = (entry: ToolActivityEvent) => void;
 export interface AttachInput {
@@ -81,29 +97,45 @@ export type FetchAttachmentFn = (query: {
 export type ProgressFn = (update: {
     percentage: number;
 } | null) => void;
-export type RagSearchFn = (input: {
-    query: string;
-    limit?: number;
-}) => Promise<RagSearchResult>;
-export interface RagSearchResult {
-    enabled: boolean;
-    indexEmpty: boolean;
-    hasKnowledge: boolean;
-    pendingReferenced?: boolean;
-    errorMessage?: string | null;
-    hits: ReadonlyArray<{
-        content: string;
-        metadataJson?: string | null;
-        score: number;
-    }>;
-}
 export type AskUserFn = (question: {
     question: string;
     options?: string[];
 }) => Promise<string | null>;
+export interface ToolFetchInit {
+    method?: string;
+    headers?: Record<string, string> | [string, string][];
+    body?: string | Uint8Array | ArrayBuffer;
+    signal?: BareAbortSignal;
+    redirect?: 'follow' | 'manual' | 'error';
+}
+export interface ToolFetchResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly url: string;
+    readonly redirected: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+        has(name: string): boolean;
+        entries(): IterableIterator<[string, string]>;
+    };
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+}
+export type ToolFetch = (input: string | URL, init?: ToolFetchInit) => Promise<ToolFetchResponse>;
+export interface SpillSink {
+    write(text: string): void;
+    close(): Promise<string | null>;
+}
+export interface ToolSpill {
+    readonly dir: string;
+    sink(stream: string): SpillSink;
+}
 export interface ToolExecuteContext {
     agentId?: string | null | undefined;
     skills?: readonly string[] | undefined;
+    skillsLoadedThisTurn?: readonly string[] | undefined;
     runId?: string;
     callId?: string;
     ctxSize?: number | undefined;
@@ -114,7 +146,6 @@ export interface ToolExecuteContext {
     }[] | undefined;
     attach?: AttachFn | undefined;
     fetchAttachment?: FetchAttachmentFn | undefined;
-    ragSearch?: RagSearchFn | undefined;
     progress?: ProgressFn | undefined;
     askUser?: AskUserFn | undefined;
     signal?: BareAbortSignal | undefined;
@@ -127,6 +158,20 @@ export interface ToolExecuteContext {
     sandboxMode?: boolean | undefined;
     toolNames?: readonly string[] | undefined;
     approval?: ToolDecision | undefined;
+    fetch?: ToolFetch | undefined;
+    knowledge?: KnowledgeGrant | undefined;
+    spill?: ToolSpill | undefined;
+    planMode?: boolean | undefined;
+    callTool?: CallTool | undefined;
+    history?: readonly Message[] | undefined;
+}
+export interface CallTool {
+    (name: string, args: unknown): Promise<unknown>;
+    readonly names: readonly string[];
+}
+export type Toolset = 'web-search' | 'knowledge' | 'files' | 'exec' | 'http-request' | 'mcp-call' | 'image' | 'music' | 'coding' | 'team';
+export interface ToolsetScoped {
+    toolset?: string | null;
 }
 export type ToolParameterType = 'string' | 'number' | 'boolean' | 'object' | 'integer' | 'array' | 'null';
 export interface ToolParameterSchema {
@@ -137,6 +182,7 @@ export interface ToolParameterSchema {
     items?: ToolParameterSchema;
     properties?: Record<string, ToolParameterSchema>;
     required?: string[];
+    default?: unknown;
 }
 export interface ToolParameters {
     type: 'object';
@@ -147,6 +193,7 @@ export interface ToolPromptDefinition {
     description?: string;
     parameters?: ToolParameters;
 }
+export type AddonLoaders = Readonly<Record<string, () => Promise<unknown>>>;
 export interface ToolDefinition {
     name: string;
     policyVersion?: string;
@@ -163,8 +210,17 @@ export interface ToolDefinition {
     validate?: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => string | null;
     effect: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => ToolEffect;
     resource?: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => ResourceDescriptor | null;
+    quote?: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => string | null;
+    egress?: (args: Record<string, unknown>) => string | readonly string[] | null;
     compiled?: true;
+    endsRun?: true;
+    concurrent?: true;
+    callsTools?: true;
+    defer?: true;
+    group?: string;
+    minCapabilityProfile?: CapabilityProfile;
     landedWrite?: (args: Record<string, unknown>, output: unknown) => string | null;
+    addons?: AddonLoaders;
     execute: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => Promise<unknown>;
 }
 export interface ToolCallEvent {
@@ -199,11 +255,15 @@ export interface MetricsEvent {
     type: 'metrics';
     totalTokens: number;
     durationMs: number;
+    modelMs?: number | undefined;
+    toolMs?: number | undefined;
     timeToFirstToken?: number | undefined;
     tokensPerSecond?: number | undefined;
     promptTokensPerSecond?: number | undefined;
     promptTokens?: number | undefined;
     cacheTokens?: number | undefined;
+    rounds?: RoundSpeed[] | undefined;
+    tools?: ToolSpeed[] | undefined;
     ctxSize?: number | undefined;
     backends?: RunBackendUse[] | undefined;
     usage?: UsageBreakdown | undefined;
@@ -227,6 +287,44 @@ export interface InferenceCallEvent {
     type: 'inference-call';
     call: InferenceCall;
 }
+export type TransferEvent = {
+    type: 'transfer';
+    from: string;
+    to: string;
+    reason: string;
+};
+export interface RunInput {
+    mode: 'steer' | 'follow-up';
+    text: string;
+    id?: string;
+}
+export interface InputEvent {
+    type: 'input';
+    id?: string;
+    text: string;
+    round: number;
+}
+export interface InputRejectedEvent {
+    type: 'input-rejected';
+    reason: string;
+}
+export interface GoalEvent {
+    type: 'goal';
+    status: GoalStatus;
+    turn: number;
+    round: number;
+    text?: string;
+}
+export type FoldEvent = {
+    type: 'fold';
+    phase: 'start';
+} | {
+    type: 'fold';
+    phase: 'done';
+    summary: string;
+    throughId: string;
+    foldedTurns: number;
+};
 export interface InferenceSentEvent {
     type: 'inference-sent';
     round: number;
@@ -242,10 +340,11 @@ export interface InferenceTokens {
     cached?: number | undefined;
     timeToFirstToken?: number | undefined;
 }
-export type CompletionEvent = (RunLifecycleEvent | TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent | InferenceCallEvent | InferenceSentEvent) & {
+export type CompletionEvent = (RunLifecycleEvent | TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent | InferenceCallEvent | InferenceSentEvent | TransferEvent | InputEvent | InputRejectedEvent | GoalEvent | FoldEvent) & {
     runId?: string;
     round?: number;
     callId?: string;
+    agent?: string;
 };
 export interface CompletionSdkResult {
     requestId?: string;
@@ -279,9 +378,24 @@ export interface CompletionSdk {
     cancel?(params: {
         requestId: string;
     }): Promise<void>;
+    deleteCache?(params: {
+        kvCacheKey: string;
+    }): Promise<{
+        success: boolean;
+    }>;
 }
 export interface RoundModelLease {
     modelId: string;
+    ctxSize?: number | undefined;
     sdk?: CompletionSdk;
     release: () => void;
 }
+export interface ResolvedCall {
+    call: ToolCallWithCall;
+    tool?: ToolDefinition;
+    args: Record<string, unknown>;
+    rawCall?: string;
+    intent?: string;
+    rejection?: HookRejection;
+    permission?: 'allow' | 'ask';
+}

package/dist-lib/lib/contract/exec.d.ts

@@ -0,0 +1,134 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { AskUserFn, AttachFn, FetchAttachmentFn, RunBudget, ToolDecision, ToolEffect, ToolExecuteContext, ToolParameterSchema, ToolSpill } from './index.ts';
+export interface ExecAttachment {
+    readonly attachmentId: string;
+    readonly fileName: string;
+    readonly byteLength: number;
+}
+export interface RejectedOutput {
+    readonly name: string;
+    readonly reason: string;
+}
+export interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly attachments?: readonly ExecAttachment[];
+    readonly missingOutputs?: readonly string[];
+    readonly rejectedOutputs?: readonly RejectedOutput[];
+}
+export interface SpawnOptions {
+    cwd?: string;
+    shell?: boolean;
+    detached?: boolean;
+    stdio?: [string, string, string] | string;
+    env?: Record<string, string>;
+}
+export interface Child {
+    readonly pid?: number;
+    readonly stdout: {
+        on(event: 'data', handler: (chunk: Buffer | string) => void): void;
+    } | null;
+    readonly stderr: {
+        on(event: 'data', handler: (chunk: Buffer | string) => void): void;
+    } | null;
+    kill(signum?: number | string): void;
+    on(event: 'exit', handler: (code: number | null, signal?: string | null) => void): void;
+    on(event: 'error', handler: (err: Error) => void): void;
+}
+export type SpawnFn = (command: string, opts?: SpawnOptions) => Child;
+export type KillProcess = (pid: number, signal: string) => void;
+export interface ShellRuntime {
+    readonly spawn: SpawnFn;
+    readonly killProcess?: KillProcess;
+}
+export interface ExecutionOptions {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+    readonly maxOutputChars?: number;
+    readonly signal?: BareAbortSignal;
+    readonly spill?: ToolSpill;
+}
+export interface ExecutionContext {
+    readonly attach?: AttachFn;
+    readonly fetchAttachment?: FetchAttachmentFn;
+    readonly turnImages?: readonly {
+        path: string;
+    }[];
+    readonly runBudget?: RunBudget;
+    readonly sandboxMode?: boolean;
+    readonly toolNames?: readonly string[];
+    readonly approval?: ToolDecision;
+    readonly askUser?: AskUserFn;
+    readonly writeRoots?: readonly string[];
+    readonly deniedRoots?: readonly string[];
+}
+export interface ExecutionPlan {
+    run(options: ExecutionOptions): Promise<ExecResult> | ExecResult;
+}
+export interface ExecutionAdapter {
+    resolve(args: Record<string, unknown>, ctx?: ExecutionContext): ExecutionPlan | null;
+}
+export interface FallbackExecutionAdapter {
+    resolve(args: Record<string, unknown>, ctx?: ExecutionContext): ExecutionPlan;
+}
+export interface ExecShell extends FallbackExecutionAdapter {
+    readonly name: string;
+}
+export interface ExecError {
+    error: string;
+}
+export interface ExecLanguageWording {
+    readonly runs: string;
+    readonly guide: string;
+    readonly command: string;
+    readonly language: string;
+    readonly properties: Readonly<Record<string, ToolParameterSchema>>;
+}
+export interface ExecLanguageText extends ExecLanguageWording {
+    readonly workdir: string;
+    readonly download: string;
+    readonly prompt: ExecLanguageWording;
+}
+export interface ExecScope {
+    readonly sandbox: boolean;
+}
+export interface ExecValidateScope extends ExecScope {
+    readonly trusted: boolean;
+    readonly toolNames?: readonly string[] | undefined;
+}
+export interface LanguageRun {
+    readonly args: Record<string, unknown>;
+    readonly trusted: boolean;
+}
+export interface LanguageCall {
+    readonly args: Record<string, unknown>;
+    readonly bundled?: {
+        readonly label: string;
+        load(skillsDir: string | undefined): LanguageRun | ExecError;
+    };
+}
+export interface ExecLanguage extends ExecutionAdapter {
+    readonly name: string;
+    readonly text: ExecLanguageText;
+    call(args: Record<string, unknown>): LanguageCall | ExecError | null;
+    effect(args: Record<string, unknown>): ToolEffect;
+    scope(args: Record<string, unknown>, scope: ExecScope): string | null;
+    validate(args: Record<string, unknown>, scope: ExecValidateScope): string | null;
+    label(args: Record<string, unknown>, scope: ExecScope): string;
+    online(scope: ExecScope): boolean;
+    redirect(args: Record<string, unknown>, scope: ExecScope): string | null;
+    strays(args: Record<string, unknown>): string | null;
+}
+export interface ExecRouteOptions {
+    readonly timeoutMs?: number;
+    readonly maxOutputChars?: number;
+    readonly signal?: BareAbortSignal;
+    readonly runtime: () => Promise<ShellRuntime>;
+}
+export interface ExecRoute {
+    readonly name: string;
+    claims(command: string): boolean;
+    run(command: string, ctx: ToolExecuteContext | undefined, options: ExecRouteOptions): Promise<ExecResult>;
+}

package/dist-lib/lib/{hooks/types.d.ts → contract/hooks.d.ts}

@@ -1,8 +1,7 @@
-import type { HookRejection } from '../machine/index.ts';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
-import type { ToolExecutionOutcome } from '../tool-call-display.ts';
-import type { Message, ResourceDescriptor, ToolDefinition, ToolEffect } from '../capabilities/completion.ts';
-export type HookPhase = 'runStart' | 'preToolCall' | 'postToolCall' | 'runEnd' | 'runPause' | 'runResume';
+import type { ToolDefinition } from './completion.ts';
+import type { HookRejection, Message, ResourceDescriptor, ToolEffect, ToolExecutionOutcome } from './run.ts';
+export type HookPhase = 'runStart' | 'preToolCall' | 'postToolCall' | 'runEnd' | 'runPause' | 'runResume' | 'promptSubmit' | 'toolFailure' | 'stop' | 'preFold';
 export interface RunStartPayload {
     readonly phase: 'runStart';
     readonly runId: string;
@@ -19,6 +18,9 @@ export interface PreToolCallPayload {
     readonly skillNames?: readonly string[];
     readonly parameters?: ToolDefinition['parameters'];
     readonly sandboxMode?: boolean;
+    readonly egress?: ToolDefinition['egress'];
+    readonly effect: ToolEffect;
+    readonly resource: ResourceDescriptor | null;
     args: Record<string, unknown>;
 }
 export interface PostToolCallPayload {
@@ -52,18 +54,68 @@ export interface RunLifecyclePayload {
     readonly runId: string;
     readonly agentId: string | null;
 }
-export type HookContext = RunLifecyclePayload | RunStartPayload | PreToolCallPayload | PostToolCallPayload | RunEndPayload;
-export type { HookRejection };
-export interface PreToolCallResult {
+export interface PromptSubmitPayload {
+    readonly phase: 'promptSubmit';
+    readonly runId: string;
+    readonly agentId: string | null;
+    readonly mode: 'prompt' | 'steer' | 'follow-up';
+    readonly text: string;
+}
+export interface ToolFailurePayload {
+    readonly phase: 'toolFailure';
+    readonly runId: string;
+    readonly callId: string;
+    readonly toolName: string;
+    readonly agentId: string | null;
     readonly args: Record<string, unknown>;
+    readonly executed: boolean;
+    readonly outcome: ToolExecutionOutcome;
+    readonly result: unknown;
+}
+export interface StopPayload {
+    readonly phase: 'stop';
+    readonly runId: string;
+    readonly agentId: string | null;
+    readonly round: number;
+    readonly response: string;
+}
+export interface PreFoldPayload {
+    readonly phase: 'preFold';
+    readonly runId: string;
+    readonly agentId: string | null;
+    readonly messages: ReadonlyArray<Message>;
+}
+export type HookContext = RunLifecyclePayload | RunStartPayload | PreToolCallPayload | PostToolCallPayload | RunEndPayload | PromptSubmitPayload | ToolFailurePayload | StopPayload | PreFoldPayload;
+export interface PreToolCallResult {
+    readonly args?: Record<string, unknown>;
+    readonly permission?: 'allow' | 'deny' | 'ask';
+    readonly reason?: string;
 }
 export interface PostToolCallResult {
-    readonly result: unknown;
+    readonly result?: unknown;
+    readonly context?: string;
+}
+export interface ContextResult {
+    readonly context: string;
+}
+export interface HaltResult {
+    readonly halt: string;
+}
+export interface ContinueResult {
+    readonly continue: string;
+}
+export interface InstructionsResult {
+    readonly instructions: string;
 }
 export type HookRejectionResult = Omit<HookRejection, 'hook' | 'phase'>;
-export type HookResult = PreToolCallResult | PostToolCallResult | HookRejectionResult | void;
+export type HookResult = PreToolCallResult | PostToolCallResult | ContextResult | HaltResult | ContinueResult | InstructionsResult | HookRejectionResult | void;
+export interface HookRunOptions {
+    readonly signal?: BareAbortSignal | undefined;
+}
 export interface HarnessHook {
     readonly name?: string;
     readonly phase: HookPhase;
-    run(ctx: HookContext): Promise<HookResult> | HookResult;
+    readonly matcher?: string;
+    readonly timeoutMs?: number;
+    run(ctx: HookContext, options?: HookRunOptions): Promise<HookResult> | HookResult;
 }

package/dist-lib/lib/contract/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './agent.ts';
+export type * from './completion.ts';
+export type * from './hooks.ts';
+export type * from './run.ts';
+export type * from './skill-readiness.ts';