@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/subagents.js

@@ -0,0 +1,136 @@
+import { takeChars } from "../core/text.js";
+import { findRun, loadRun, readEvents } from "./runStore.js";
+export const SPAWN_SUBAGENT = 'spawn_subagent';
+export const WAIT_SUBAGENTS = 'wait_subagents';
+export const SUBAGENT_RELATION = 'subagent';
+/** How deep subagents may nest when the caller does not say. */
+export const DEFAULT_SUBAGENT_DEPTH = 1;
+export const MAX_SUBAGENT_DEPTH = 3;
+/** How many distinct children a run may start when the caller does not say. */
+export const DEFAULT_SUBAGENT_CHILDREN = 4;
+/** The most a host may allow, so a mistyped setting cannot lift the budget entirely. */
+export const MAX_SUBAGENT_CHILDREN = 50;
+/** Foundation limits for the profiles the harness ships; `maxByProfile` overrides them. */
+export const DEFAULT_SUBAGENT_PROFILE_CHILDREN = { worker: 2, explorer: 3 };
+export const DEFAULT_SUBAGENT_OTHER_PROFILE = 1;
+export const DEFAULT_SUBAGENT_UNPROFILED = 1;
+/** The bucket a child with no profile counts against. No profile name can be `*`. */
+export const UNPROFILED_SUBAGENT = '*';
+function limit(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.min(MAX_SUBAGENT_CHILDREN, Math.max(0, Math.trunc(value)));
+}
+/** The effective budget: the caller's values merged over the foundation defaults. */
+export function subagentQuota(options) {
+    const profiles = { ...DEFAULT_SUBAGENT_PROFILE_CHILDREN };
+    const given = options?.maxByProfile;
+    if (given && typeof given === 'object' && !Array.isArray(given)) {
+        for (const [raw, value] of Object.entries(given)) {
+            const name = raw.trim();
+            if (!name || name.length > 64 || /[\x00-\x1f\x7f]/u.test(name))
+                continue;
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                continue;
+            profiles[name] = limit(value, profiles[name] ?? DEFAULT_SUBAGENT_OTHER_PROFILE);
+        }
+    }
+    return {
+        children: limit(options?.maxChildren, DEFAULT_SUBAGENT_CHILDREN),
+        profiles,
+        other: limit(options?.maxOther, DEFAULT_SUBAGENT_OTHER_PROFILE),
+        unprofiled: limit(options?.maxUnprofiled, DEFAULT_SUBAGENT_UNPROFILED)
+    };
+}
+/** The bucket a child counts against: its profile name, or the unprofiled bucket. */
+export function subagentProfileKey(profile) {
+    const name = typeof profile === 'string' ? profile.trim() : '';
+    return name || UNPROFILED_SUBAGENT;
+}
+/** How many children this profile may still start under the quota. */
+export function subagentProfileLimit(quota, key) {
+    return key === UNPROFILED_SUBAGENT ? quota.unprofiled : quota.profiles[key] ?? quota.other;
+}
+export function subagentDepth(options) {
+    const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH);
+    return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH));
+}
+/** The words that tell a parent a stopped child can be continued rather than started again. */
+export function continueHint(runId) {
+    return `Its conversation is saved: continue it with spawn_subagent { "continue": "${runId}" } if the work is still needed, instead of starting it again from scratch.`;
+}
+/** A subagent title is one short imperative, at most this many words (PROP-0030). */
+export const MAX_SUBAGENT_TITLE_WORDS = 6;
+const BRIEF_TITLE_LENGTH = 60;
+/** The title a subagent title input means after cleaning, or undefined when it is not one. */
+export function subagentTitle(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (/[\x00-\x08\x0e-\x1f\x7f-\x9f]/u.test(value))
+        return undefined;
+    const title = value.replace(/\s+/gu, ' ').trim();
+    if (!title || title.split(' ').length > MAX_SUBAGENT_TITLE_WORDS)
+        return undefined;
+    return title;
+}
+/** A title read from a brief when the caller gave none: its first line, cut to a short length. */
+export function briefTitle(brief) {
+    const line = (brief ?? '').split('\n').map((part) => part.replace(/\s+/gu, ' ').trim()).find(Boolean) ?? '';
+    return line.length > BRIEF_TITLE_LENGTH ? `${line.slice(0, BRIEF_TITLE_LENGTH - 1)}…` : line;
+}
+export const SUBAGENT_RECEIPT = 'xingularSubagents';
+export const SUBAGENT_OWNER = 'xingular-subagent-owner';
+export const SUBAGENT_RESULTS = 'xingular-subagent-results';
+/** Read explicit native metadata, including entries retained before compaction. */
+export function subagentHistory(entries) {
+    const owners = [];
+    const receipts = [];
+    for (const raw of entries) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const entry = raw;
+        if (entry.type === 'custom' && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === 'string')
+            owners.push(entry.data.runId);
+        const message = entry.type === 'message' ? entry.message : entry;
+        const receipt = message?.details?.[SUBAGENT_RECEIPT];
+        if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== 'string')
+            continue;
+        const strings = (value) => Array.isArray(value) && value.every((id) => typeof id === 'string');
+        if ((receipt.spawned !== undefined && !strings(receipt.spawned)) || (receipt.delivered !== undefined && !strings(receipt.delivered)))
+            continue;
+        receipts.push(receipt);
+    }
+    return { owners, receipts };
+}
+/** Native nesting is independent of a host's other uses of the generic caller depth. */
+export function subagentNesting(root, run) {
+    let current = run;
+    let depth = 0;
+    const visited = new Set();
+    while (current.relation === SUBAGENT_RELATION) {
+        const parent = current.parentRunId;
+        if (!parent || visited.has(parent))
+            return MAX_SUBAGENT_DEPTH;
+        visited.add(parent);
+        depth++;
+        const record = findRun(root, parent);
+        if (!record)
+            return MAX_SUBAGENT_DEPTH;
+        current = record;
+    }
+    return depth;
+}
+/** The child's final reply, or why it ended without one. */
+export function subagentReport(root, runId) {
+    const run = loadRun(root, runId);
+    const reply = readEvents(root, runId).filter((event) => event.type === 'message.completed' && event.payload.role === 'assistant').at(-1);
+    const text = typeof reply?.payload?.text === 'string' ? takeChars(reply.payload.text, 16_000) : '';
+    const lines = [`Subagent run ${runId} · ${run.status}`];
+    if (text)
+        lines.push(`Result:\n${text}`);
+    else if (run.status === 'completed')
+        lines.push('It finished without a written reply.');
+    if (run.status !== 'completed' && run.terminalReason)
+        lines.push(`Stopped because: ${run.terminalReason}`);
+    return lines.join('\n');
+}

package/dist/sdk/sessions/workSlice.d.ts

@@ -0,0 +1,167 @@
+import type { Checkpoint } from "./contracts.js";
+export declare const WORK_SLICE_EXTENSION = "work-slice";
+export interface WorkSliceInput {
+    /** False turns the guard off for this run: no budget, no handoff request, no continuation. */
+    enabled?: boolean;
+    /** Tool calls in one reply; 0 disables this limit. */
+    maxToolCalls?: number;
+    /** Minutes in one reply; 0 disables this limit. */
+    maxMinutes?: number;
+    /** New tokens in one reply (new input + cache writes + output); 0 disables this limit, and no limit is the default. */
+    maxNewTokens?: number;
+    /** Slices one task may use before it is handed back to the person; 0 disables the cap. */
+    maxSlices?: number;
+    /** Start the next slice from the checkpoint without asking. */
+    continue?: boolean;
+}
+export interface SlicePolicy {
+    enabled: boolean;
+    maxToolCalls: number;
+    maxMinutes: number;
+    maxNewTokens: number;
+    maxSlices: number;
+    continue: boolean;
+}
+/**
+ * The foundation defaults: no budget (ADR-0081). A reply is not cut at a number of tool calls, a
+ * length of time or a number of tokens, and nothing is continued as a "next slice"; it ends when the
+ * work is done, a person's decision is needed, or the person interrupts. The limits stay available
+ * to a caller that asks for one (`workSlice`, `XINGULAR_WORK_SLICE`), and the three-compaction guard
+ * is not a budget and stays on.
+ */
+export declare const DEFAULT_SLICE_POLICY: SlicePolicy;
+export declare class WorkSliceError extends Error {
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export declare function parseWorkSlice(input: unknown): SlicePolicy;
+export type SliceEnd = 'budget' | 'compaction-thrash';
+/** What a live reply tracks for its slice; the runner reads it after the reply. */
+export interface SliceState {
+    slice: number;
+    steps: number;
+    tokens: number;
+    startedAt: number;
+    lastTool: string | null;
+    compactions: number;
+    /** Set when the guard ended the reply instead of the model finishing it. */
+    endedBy: SliceEnd | null;
+    /** The limit that ended it, for the record. */
+    endedByLimit: string | null;
+    /** Steps past which every non-exempt tool call is refused, once one was refused. */
+    refusedAt: number | null;
+    /** Whether this slice did work: a successful command or file change. A fruitless slice is not continued. */
+    progressed: boolean;
+}
+export declare function createSliceState(_policy: SlicePolicy, slice?: number, now?: number): SliceState;
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export declare function resetSliceState(state: SliceState, now?: number): void;
+/**
+ * The next slice of the same reply: fresh counters and clock, one more slice. Compactions carry
+ * over, so a reply that keeps compacting still ends.
+ */
+export declare function beginNextSlice(state: SliceState, now?: number): void;
+/** The first limit this reply has passed, named as a person would say it. */
+export declare function sliceLimitReached(policy: SlicePolicy, state: SliceState, now?: number): string | null;
+interface ToolCall {
+    toolCallId: string;
+    toolName: string;
+}
+/** The part of Pi's extension API this guard uses. Structural, so the module needs no Pi import. */
+interface GuardApi {
+    on(event: 'before_agent_start', handler: (event: {
+        messageType?: string;
+    }) => unknown): void;
+    on(event: 'tool_call', handler: (event: ToolCall) => unknown): void;
+    on(event: 'message_end', handler: (event: {
+        message: {
+            role: string;
+            usage?: {
+                input?: number;
+                output?: number;
+                cacheRead?: number;
+                cacheWrite?: number;
+            };
+        };
+    }) => unknown): void;
+}
+export interface WorkSliceGuardOptions {
+    policy: SlicePolicy;
+    state: SliceState;
+    /** Called when a triggering call terminates the reply; the runner ends it. */
+    onEnd?: (end: SliceEnd, limit: string) => void;
+    onRefuse?: (event: ToolCall, reason: string) => void;
+}
+/**
+ * Bounds one reply. A call past the budget is refused with one wrap-up request, and an ended reply
+ * lets only a handoff call through. Three compactions in one reply end it too. Every other call is
+ * allowed, however often it is made.
+ */
+export declare function workSliceGuard(options: WorkSliceGuardOptions): (pi: GuardApi) => void;
+export declare const SLICE_CONTINUE_CUSTOM_TYPE = "xingular-slice-continue";
+/** The part of Pi's extension API the continuation uses. Structural, so the module needs no Pi import. */
+interface ContinuationApi {
+    on(event: 'before_agent_start', handler: (event: {
+        messageType?: string;
+    }) => unknown): void;
+    on(event: 'tool_result', handler: (event: {
+        toolName: string;
+        isError?: boolean;
+    }) => unknown): void;
+    on(event: 'agent_before_settle', handler: (event: {
+        outcome?: string;
+        continue?: boolean;
+        entries: unknown[];
+    }, ctx?: {
+        signal?: AbortSignal;
+    }) => unknown): void;
+}
+export interface SliceContinuationOptions {
+    policy: SlicePolicy;
+    state: SliceState;
+    /** False while a plan runs: a plan is not continued. */
+    active?: () => boolean;
+    failed?: () => boolean;
+    /** True when the completion check said the reply needs the person (ADR-0071). */
+    blocked?: () => boolean;
+    /** The todo list: when every item is done, the work is not continued. */
+    todo?: () => readonly {
+        status: string;
+    }[];
+    /** The next open step, for the continue message. */
+    next?: () => string;
+    /** True while a /goal is active: a goal's slices go on even when every todo item is done (ADR-0072). */
+    goalActive?: () => boolean;
+    /** Called before the next slice starts, with the slice that ended. */
+    onContinue?: (ended: {
+        slice: number;
+        steps: number;
+        limit: string | null;
+    }) => void;
+}
+/**
+ * Continues a reply in place when its slice ended at the budget (PROP-0041, ADR-0070): the same
+ * run and the same cached prompt, with fresh counters, up to `maxSlices`. Never after a fruitless,
+ * blocked, failed, aborted or plan slice, or when every todo item is done. A person's message
+ * starts again at slice 1.
+ */
+export declare function sliceContinuation(options: SliceContinuationOptions): (pi: ContinuationApi) => void;
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export declare function sliceOf(root: string, runId: string, limit?: number): number;
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export declare function derivedReason(end: SliceEnd | null): Checkpoint['reason'];
+/** What a heartbeat reports about the tools in flight: their names once each, and the oldest one's age. */
+export declare function activeToolBeat(tools: ReadonlyMap<string, {
+    name: string;
+    at: number;
+}>, now?: number): {
+    activeTools: string[];
+    oldestToolMs: number;
+} | Record<string, never>;
+export {};

package/dist/sdk/sessions/workSlice.js

@@ -0,0 +1,266 @@
+import { findRun } from "./runStore.js";
+export const WORK_SLICE_EXTENSION = 'work-slice';
+/**
+ * The foundation defaults: no budget (ADR-0081). A reply is not cut at a number of tool calls, a
+ * length of time or a number of tokens, and nothing is continued as a "next slice"; it ends when the
+ * work is done, a person's decision is needed, or the person interrupts. The limits stay available
+ * to a caller that asks for one (`workSlice`, `XINGULAR_WORK_SLICE`), and the three-compaction guard
+ * is not a budget and stays on.
+ */
+export const DEFAULT_SLICE_POLICY = {
+    enabled: true,
+    maxToolCalls: 0,
+    maxMinutes: 0,
+    maxNewTokens: 0,
+    // Inert while no limit ends a slice; a caller that sets one gets the same continuation as before.
+    maxSlices: 8,
+    continue: true
+};
+const LIMITS = {
+    maxToolCalls: { min: 1, max: 2_000 },
+    maxMinutes: { min: 1, max: 480 },
+    maxNewTokens: { min: 1_000, max: 5_000_000 },
+    maxSlices: { min: 1, max: 100 }
+};
+export class WorkSliceError extends Error {
+}
+/** `XINGULAR_WORK_SLICE=maxToolCalls=15,maxSlices=3` at launch: the same fields as a run's policy. */
+function launchPolicy(text) {
+    const record = {};
+    for (const part of text.split(',')) {
+        const [key, raw] = part.split('=').map((value) => value.trim());
+        if (!key || raw === undefined)
+            throw new WorkSliceError(`XINGULAR_WORK_SLICE must be off or key=value pairs, not ${JSON.stringify(text)}.`);
+        record[key] = raw === 'true' ? true : raw === 'false' ? false : Number(raw);
+    }
+    return record;
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export function parseWorkSlice(input) {
+    if (input === undefined || input === null) {
+        const launch = process.env.XINGULAR_WORK_SLICE?.trim();
+        if (launch === undefined || launch === '')
+            return { ...DEFAULT_SLICE_POLICY };
+        if (['off', '0', 'false'].includes(launch.toLowerCase()))
+            return { ...DEFAULT_SLICE_POLICY, enabled: false };
+        return parseWorkSlice(launchPolicy(launch));
+    }
+    if (typeof input !== 'object' || Array.isArray(input))
+        throw new WorkSliceError('workSlice must be an object.');
+    const record = input;
+    const policy = { ...DEFAULT_SLICE_POLICY };
+    for (const key of Object.keys(record)) {
+        if (key === 'enabled') {
+            if (typeof record.enabled !== 'boolean')
+                throw new WorkSliceError('workSlice.enabled must be true or false.');
+            policy.enabled = record.enabled;
+            continue;
+        }
+        if (key === 'continue') {
+            if (typeof record.continue !== 'boolean')
+                throw new WorkSliceError('workSlice.continue must be true or false.');
+            policy.continue = record.continue;
+            continue;
+        }
+        const limits = LIMITS[key];
+        if (!limits)
+            throw new WorkSliceError(`workSlice has no field ${key}.`);
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isInteger(value))
+            throw new WorkSliceError(`workSlice.${key} must be a whole number.`);
+        // 0 switches one limit off, as the settings page says.
+        if (value === 0) {
+            policy[key] = 0;
+            continue;
+        }
+        if (value < limits.min || value > limits.max)
+            throw new WorkSliceError(`workSlice.${key} must be between ${limits.min} and ${limits.max}, or 0 for no limit.`);
+        policy[key] = value;
+    }
+    return policy;
+}
+export function createSliceState(_policy, slice = 1, now = Date.now()) {
+    return { slice, steps: 0, tokens: 0, startedAt: now, lastTool: null, compactions: 0, endedBy: null, endedByLimit: null, refusedAt: null, progressed: false };
+}
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export function resetSliceState(state, now = Date.now()) {
+    state.steps = 0;
+    state.tokens = 0;
+    state.startedAt = now;
+    state.lastTool = null;
+    state.compactions = 0;
+    state.endedBy = null;
+    state.endedByLimit = null;
+    state.refusedAt = null;
+    state.progressed = false;
+}
+/**
+ * The next slice of the same reply: fresh counters and clock, one more slice. Compactions carry
+ * over, so a reply that keeps compacting still ends.
+ */
+export function beginNextSlice(state, now = Date.now()) {
+    const compactions = state.compactions;
+    resetSliceState(state, now);
+    state.compactions = compactions;
+    state.slice += 1;
+}
+/** The first limit this reply has passed, named as a person would say it. */
+export function sliceLimitReached(policy, state, now = Date.now()) {
+    if (policy.maxToolCalls > 0 && state.steps >= policy.maxToolCalls)
+        return `${policy.maxToolCalls} tool calls`;
+    if (policy.maxMinutes > 0 && now - state.startedAt >= policy.maxMinutes * 60_000)
+        return `${policy.maxMinutes} minutes`;
+    if (policy.maxNewTokens > 0 && state.tokens >= policy.maxNewTokens)
+        return `${Math.round(policy.maxNewTokens / 1000)}k new tokens`;
+    return null;
+}
+/** Tools a reply may still call after its slice ended. A plan update waits for the next slice. */
+const HANDOFF_TOOLS = new Set(['session_name']);
+const clip = (value, limit) => (value.length <= limit ? value : `${value.slice(0, limit - 1)}…`);
+// The harness writes the handoff itself from the reply's files, checks and todo list (ADR-0069), so
+// the model is only asked to stop and say where it is.
+function handoffRequest(limit, state) {
+    return clip(`This reply reached its work-slice limit (${limit}; step ${state.steps}). Stop using tools and write a short report: what is done or found, what is left, and the single next step. ` +
+        'The Harness records a checkpoint from this reply\'s evidence, and the next slice continues from it. Do not call other tools.', 600);
+}
+/**
+ * Bounds one reply. A call past the budget is refused with one wrap-up request, and an ended reply
+ * lets only a handoff call through. Three compactions in one reply end it too. Every other call is
+ * allowed, however often it is made.
+ */
+export function workSliceGuard(options) {
+    const { policy, state } = options;
+    const end = (kind, limit) => {
+        state.endedBy = kind;
+        state.endedByLimit = limit;
+        options.onEnd?.(kind, limit);
+        const reason = kind === 'compaction-thrash'
+            ? handoffRequest('three context compactions in one reply', state)
+            : handoffRequest(limit, state);
+        return { block: true, terminate: true, reason };
+    };
+    return (pi) => {
+        // Pi emits agent_start again for every continuation (a slice continuation, delivered subagent
+        // results, a plan repair), and those belong to the same reply and the same budget. Only a
+        // person's message starts a new slice.
+        pi.on('before_agent_start', (event) => {
+            if (event.messageType !== undefined && event.messageType !== 'user')
+                return;
+            resetSliceState(state);
+        });
+        pi.on('message_end', (event) => {
+            const usage = event.message.usage;
+            if (event.message.role !== 'assistant' || !usage)
+                return;
+            // New tokens only: the cached prefix was sent before and is not new context or new cost.
+            state.tokens += (usage.input ?? 0) + (usage.cacheWrite ?? 0) + (usage.output ?? 0);
+        });
+        pi.on('tool_call', (event) => {
+            const name = event.toolName;
+            const refuse = (result) => { options.onRefuse?.(event, result.reason); return result; };
+            state.steps += 1;
+            state.lastTool = name;
+            const handoff = HANDOFF_TOOLS.has(name);
+            // After the slice ended, a handoff call is the only one that runs.
+            if (state.endedBy) {
+                const reason = 'This reply is over. The Harness will record an evidence-derived checkpoint; nothing else runs.';
+                return handoff ? undefined : refuse({ block: true, terminate: true, reason });
+            }
+            if (state.compactions >= 3) {
+                if (handoff) {
+                    state.endedBy = 'compaction-thrash';
+                    state.endedByLimit = 'three compactions';
+                    return undefined;
+                }
+                return refuse(end('compaction-thrash', 'three compactions'));
+            }
+            const limit = sliceLimitReached(policy, state);
+            if (limit) {
+                // The slice ends here; the model gets one wrap-up request to report where it is. A handoff
+                // call is never refused, including when it is the very first call past the budget.
+                state.endedBy = 'budget';
+                state.endedByLimit = limit;
+                state.refusedAt ??= state.steps;
+                return handoff ? undefined : refuse({ block: true, reason: handoffRequest(limit, state) });
+            }
+        });
+    };
+}
+export const SLICE_CONTINUE_CUSTOM_TYPE = 'xingular-slice-continue';
+/** Successful tools that change the workspace count as progress. */
+const PROGRESS_TOOLS = new Set(['bash', 'edit', 'write']);
+/**
+ * Continues a reply in place when its slice ended at the budget (PROP-0041, ADR-0070): the same
+ * run and the same cached prompt, with fresh counters, up to `maxSlices`. Never after a fruitless,
+ * blocked, failed, aborted or plan slice, or when every todo item is done. A person's message
+ * starts again at slice 1.
+ */
+export function sliceContinuation(options) {
+    const { policy, state } = options;
+    return (pi) => {
+        pi.on('before_agent_start', (event) => {
+            if (event.messageType !== undefined && event.messageType !== 'user')
+                return;
+            state.slice = 1;
+        });
+        pi.on('tool_result', (event) => {
+            if (!event.isError && PROGRESS_TOOLS.has(event.toolName))
+                state.progressed = true;
+        });
+        pi.on('agent_before_settle', (event, ctx) => {
+            if (event.outcome !== 'completed' || event.continue || ctx?.signal?.aborted)
+                return;
+            if (!policy.enabled || !policy.continue || state.endedBy !== 'budget')
+                return;
+            if (options.active && !options.active())
+                return;
+            if (options.failed?.() || options.blocked?.() || !state.progressed)
+                return;
+            if (state.slice >= policy.maxSlices)
+                return;
+            const todo = options.todo?.() ?? [];
+            if (!options.goalActive?.() && todo.length && todo.every((item) => item.status === 'completed'))
+                return;
+            const ended = { slice: state.slice, steps: state.steps, limit: state.endedByLimit };
+            options.onContinue?.(ended);
+            beginNextSlice(state);
+            const next = options.next?.().trim();
+            const content = clip(`Work slice ${ended.slice} reached its limit (${ended.limit ?? 'budget'}). Slice ${state.slice} of up to ${policy.maxSlices} starts now with a fresh budget. ` +
+                `Continue the task from ${next ? `the next step: ${next}` : 'the next step you reported'}. Do not redo finished work.`, 900);
+            return {
+                entries: [...event.entries, { type: 'custom_message', customType: SLICE_CONTINUE_CUSTOM_TYPE, content, display: true }],
+                continue: true
+            };
+        });
+    };
+}
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export function sliceOf(root, runId, limit = 100) {
+    let current = runId;
+    let count = 0;
+    const seen = new Set();
+    while (current && count < limit && !seen.has(current)) {
+        seen.add(current);
+        count += 1;
+        current = findRun(root, current)?.resumedFromRunId ?? null;
+    }
+    return Math.max(1, count);
+}
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export function derivedReason(end) {
+    return end ?? 'requested';
+}
+/** What a heartbeat reports about the tools in flight: their names once each, and the oldest one's age. */
+export function activeToolBeat(tools, now = Date.now()) {
+    if (!tools.size)
+        return {};
+    const names = [...new Set([...tools.values()].map((tool) => tool.name))].slice(0, 16);
+    return { activeTools: names, oldestToolMs: Math.max(0, now - Math.min(...[...tools.values()].map((tool) => tool.at))) };
+}

package/dist/sdk/sessions/workspaceBoundary.d.ts

@@ -0,0 +1,15 @@
+import type { RunRecord } from "./contracts.js";
+import type { ScopeDecision } from "./policy.js";
+export declare const WORKSPACE_FILE_WRITE_TOOLS: Set<string>;
+export interface WorkspaceWriteInspection {
+    input: unknown;
+    path: string | null;
+    outside: boolean;
+    reason: string | null;
+}
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export declare function inspectWorkspaceWrite(workspaceRoot: string, cwd: string, tool: string, input: unknown): WorkspaceWriteInspection;
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export declare function combineWorkspaceScope(scope: ScopeDecision, inspection: WorkspaceWriteInspection): ScopeDecision;
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export declare function inspectRunWorkspaceWrite(run: RunRecord, tool: string, input: unknown): WorkspaceWriteInspection;

package/dist/sdk/sessions/workspaceBoundary.js

@@ -0,0 +1,46 @@
+import { isWithinWorkspace, resolveWorkspaceRoot, resolveWritePath, verifyWorkspaceRoot } from "../core/workspace.js";
+export const WORKSPACE_FILE_WRITE_TOOLS = new Set(['edit', 'write']);
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export function inspectWorkspaceWrite(workspaceRoot, cwd, tool, input) {
+    if (!WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()) || !input || typeof input !== 'object' || Array.isArray(input)) {
+        return { input, path: null, outside: false, reason: null };
+    }
+    const args = input;
+    if (typeof args.path !== 'string')
+        return { input, path: null, outside: false, reason: null };
+    const root = verifyWorkspaceRoot(workspaceRoot);
+    const path = resolveWritePath(args.path, cwd);
+    const outside = !isWithinWorkspace(root, path);
+    return {
+        input: { ...args, path },
+        path,
+        outside,
+        reason: outside ? `Write target ${path} is outside the active project workspace ${root}.` : null
+    };
+}
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export function combineWorkspaceScope(scope, inspection) {
+    if (!inspection.outside)
+        return scope;
+    if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+        return scope;
+    return {
+        ...scope,
+        allowed: false,
+        requiresApproval: true,
+        humanOnly: true,
+        allowGlobalApproval: scope.humanOnly ? scope.allowGlobalApproval : true,
+        reason: inspection.reason
+    };
+}
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export function inspectRunWorkspaceWrite(run, tool, input) {
+    const cwd = run.workingDirectory;
+    const root = run.workspaceRoot ?? (cwd ? resolveWorkspaceRoot(cwd) : null);
+    if (!root || !cwd) {
+        if (WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()))
+            throw new Error('The active project workspace could not be resolved; file writes are blocked.');
+        return { input, path: null, outside: false, reason: null };
+    }
+    return inspectWorkspaceWrite(root, cwd, tool, input);
+}