@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/dist/agent/loop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Manual agent loop for the built-in agent (#626).
+ *
+ * Wraps `scope.models.generate({ ..., toolMode: 'return' })` and dispatches
+ * any tool calls the model returns. This is a temporary stand-in for the
+ * unified `toolMode: 'auto'` orchestrator landing in #612 — when that ships,
+ * tool-call dispatch and the per-turn loop collapse into a single
+ * `generate({ ..., toolMode: 'auto' })` call. The approval/abort gates here
+ * still live in the component (the orchestrator won't know about
+ * `destructive` or operator approval semantics).
+ *
+ * Per-session serialization (one concurrent run per session) is handled
+ * here via {@link runAgent}'s in-flight map. Multiple sessions interleave
+ * on the event loop naturally because each turn is mostly awaiting the LLM
+ * or a tool's I/O.
+ */
+import type { GenerateOpts, Models } from '../resources/models/types.ts';
+import type { AgentScopes, AgentTool } from './types.ts';
+export interface RunAgentOpts {
+    sessionId: string;
+    models: Pick<Models, 'generate'>;
+    tools: AgentTool[];
+    scopes: AgentScopes;
+    maxTurns: number;
+    /** When false, destructive tools pause the loop with a pending approval instead of executing. */
+    autoApprove?: boolean;
+    signal?: AbortSignal;
+    generateOpts?: Omit<GenerateOpts, 'toolMode' | 'signal'>;
+    /** System prompt injected as the first turn when the transcript is empty. */
+    systemPrompt?: string;
+}
+export declare function runAgent(opts: RunAgentOpts): Promise<void>;
+/** Test-only: clear the in-flight tracking map. */
+export declare function _resetInFlightForTests(): void;

package/dist/agent/loop.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Manual agent loop for the built-in agent (#626).
+ *
+ * Wraps `scope.models.generate({ ..., toolMode: 'return' })` and dispatches
+ * any tool calls the model returns. This is a temporary stand-in for the
+ * unified `toolMode: 'auto'` orchestrator landing in #612 — when that ships,
+ * tool-call dispatch and the per-turn loop collapse into a single
+ * `generate({ ..., toolMode: 'auto' })` call. The approval/abort gates here
+ * still live in the component (the orchestrator won't know about
+ * `destructive` or operator approval semantics).
+ *
+ * Per-session serialization (one concurrent run per session) is handled
+ * here via {@link runAgent}'s in-flight map. Multiple sessions interleave
+ * on the event loop naturally because each turn is mostly awaiting the LLM
+ * or a tool's I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgent = runAgent;
+exports._resetInFlightForTests = _resetInFlightForTests;
+const session_ts_1 = require("./session.js");
+const toolset_ts_1 = require("./toolset.js");
+const inFlight = new Map();
+function runAgent(opts) {
+    const existing = inFlight.get(opts.sessionId);
+    if (existing)
+        return existing;
+    const run = doRun(opts).finally(() => {
+        if (inFlight.get(opts.sessionId) === run)
+            inFlight.delete(opts.sessionId);
+    });
+    inFlight.set(opts.sessionId, run);
+    return run;
+}
+async function doRun(opts) {
+    const toolMap = (0, toolset_ts_1.toolMapByName)(opts.tools);
+    const toolDefs = opts.tools.map((t) => t.def);
+    await (0, session_ts_1.setStatus)(opts.sessionId, 'running');
+    const ctx = { sessionId: opts.sessionId, signal: opts.signal, scopes: opts.scopes };
+    try {
+        // First, drain any resolved-but-unconsumed approvals from a prior pause. Either execute
+        // or refuse each saved call, recording an observation, so the next model turn sees the
+        // result of the operator decision.
+        await consumeResolvedApprovals(opts.sessionId, toolMap, ctx);
+        // If a turn produced multiple gated tool calls and the operator has only resolved some of
+        // them, the remaining approvals are still pending — meaning the assistant's tool_calls do
+        // not yet all have tool responses. Re-entering the generate loop now would send an
+        // incomplete tool-response set and the provider would 400. Stay paused until every gated
+        // call for this turn is resolved (each `approve_agent_action` re-runs this path).
+        const afterConsume = await (0, session_ts_1.getSession)(opts.sessionId);
+        if (afterConsume?.pendingApprovals.some((a) => !a.resolved)) {
+            await (0, session_ts_1.setStatus)(opts.sessionId, 'awaiting_approval');
+            return;
+        }
+        for (let turn = 0; turn < opts.maxTurns; turn++) {
+            if (opts.signal?.aborted)
+                return; // status was already set to `aborted` by cancelRun
+            const session = await (0, session_ts_1.getSession)(opts.sessionId);
+            if (!session)
+                throw new Error(`Session ${opts.sessionId} vanished mid-run`);
+            const messages = toModelMessages(session.messages, opts.systemPrompt);
+            const result = await opts.models.generate({ messages, tools: toolDefs, system: opts.systemPrompt }, { ...opts.generateOpts, toolMode: 'return', signal: opts.signal });
+            await (0, session_ts_1.appendMessage)(opts.sessionId, {
+                role: 'assistant',
+                content: result.content ?? '',
+                toolCalls: result.toolCalls,
+                createdAt: Date.now(),
+            });
+            if (!result.toolCalls || result.toolCalls.length === 0) {
+                await (0, session_ts_1.setStatus)(opts.sessionId, 'completed');
+                return;
+            }
+            const paused = await dispatchToolCalls(result.toolCalls, toolMap, ctx, opts);
+            if (paused || opts.signal?.aborted)
+                return;
+        }
+        await (0, session_ts_1.setStatus)(opts.sessionId, 'completed', `Reached maxTurns=${opts.maxTurns} without a final answer.`);
+    }
+    catch (err) {
+        // If the abort signal fired, the cancel path already set the session to `aborted` —
+        // don't clobber that with `error`. The rejection here is just the awaited generate/tool
+        // honoring the signal, not a real failure.
+        if (opts.signal?.aborted)
+            return;
+        await (0, session_ts_1.setStatus)(opts.sessionId, 'error', err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+}
+/**
+ * Returns `true` when the loop should pause (any destructive tool call required approval).
+ * Non-destructive calls execute inline and their observations are appended. Destructive calls
+ * register pending approvals but do NOT append a tool message — `consumeResolvedApprovals`
+ * writes the single tool response on the next run. This keeps the 1:1 mapping between
+ * assistant tool_calls and tool responses that LLM APIs enforce, including when the assistant
+ * message mixes destructive and non-destructive calls in the same turn.
+ */
+async function dispatchToolCalls(calls, toolMap, ctx, opts) {
+    let needsApproval = false;
+    for (const call of calls) {
+        if (opts.signal?.aborted)
+            return true;
+        const tool = toolMap.get(call.name);
+        const destructiveAndGated = tool?.destructive && !opts.autoApprove;
+        if (destructiveAndGated) {
+            await (0, session_ts_1.addPendingApproval)(opts.sessionId, {
+                toolName: call.name,
+                arguments: call.arguments ?? {},
+                toolCallId: call.id,
+                reason: 'destructive',
+            });
+            needsApproval = true;
+            // Don't break — keep processing remaining calls so non-destructive ones in the same
+            // turn still execute and write their tool responses. Their results may be useful
+            // context for the operator deciding whether to approve.
+            continue;
+        }
+        const observation = await invokeTool(call, toolMap, ctx);
+        await (0, session_ts_1.appendMessage)(opts.sessionId, {
+            role: 'tool',
+            content: observation,
+            toolCallId: call.id,
+            createdAt: Date.now(),
+        });
+    }
+    return needsApproval;
+}
+async function consumeResolvedApprovals(sessionId, toolMap, ctx) {
+    const session = await (0, session_ts_1.getSession)(sessionId);
+    if (!session)
+        return;
+    const toConsume = session.pendingApprovals.filter((a) => a.resolved && !a.consumed);
+    for (const approval of toConsume) {
+        const observation = approval.approved
+            ? await invokeTool({ id: approval.toolCallId, name: approval.toolName, arguments: approval.arguments }, toolMap, ctx)
+            : JSON.stringify({ ok: false, error: 'denied_by_operator', tool: approval.toolName });
+        await (0, session_ts_1.appendMessage)(sessionId, {
+            role: 'tool',
+            content: observation,
+            toolCallId: approval.toolCallId,
+            createdAt: Date.now(),
+        });
+        await (0, session_ts_1.markApprovalConsumed)(sessionId, approval.id);
+    }
+}
+async function invokeTool(call, toolMap, ctx) {
+    const tool = toolMap.get(call.name);
+    if (!tool)
+        return JSON.stringify({ error: 'unknown_tool', name: call.name });
+    try {
+        const result = await tool.handler(call.arguments ?? {}, ctx);
+        return JSON.stringify({ ok: true, result });
+    }
+    catch (err) {
+        return JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+}
+function toModelMessages(items, systemPrompt) {
+    const out = [];
+    if (systemPrompt && !items.some((m) => m.role === 'system')) {
+        out.push({ role: 'system', content: systemPrompt });
+    }
+    for (const item of items) {
+        const message = { role: item.role, content: item.content };
+        if (item.toolCalls)
+            message.toolCalls = item.toolCalls;
+        if (item.toolCallId)
+            message.toolCallId = item.toolCallId;
+        out.push(message);
+    }
+    return out;
+}
+/** Test-only: clear the in-flight tracking map. */
+function _resetInFlightForTests() {
+    inFlight.clear();
+}
+//# sourceMappingURL=loop.js.map

package/dist/agent/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../agent/loop.ts"],"names":[],"mappings":"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"}

package/dist/agent/operations.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Operations API surface for the built-in agent (#626).
+ *
+ * Six handlers, all super_user-only — the auth check is inline because none
+ * of these ops are registered in `utility/operation_authorization.ts`'s
+ * `requiredPermissions` map. Without the inline gate, a non-SU request would
+ * fall through the standard flow and be allowed.
+ */
+import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
+import type { AgentConfig } from './types.ts';
+export interface OperationDeps {
+    getConfig: () => AgentConfig;
+    setConfig: (patch: Partial<AgentConfig>) => AgentConfig;
+    startRun: (sessionId: string) => void;
+    cancelRun: (sessionId: string) => boolean;
+}
+export declare function buildOperations(deps: OperationDeps): OperationDefinition[];

package/dist/agent/operations.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Operations API surface for the built-in agent (#626).
+ *
+ * Six handlers, all super_user-only — the auth check is inline because none
+ * of these ops are registered in `utility/operation_authorization.ts`'s
+ * `requiredPermissions` map. Without the inline gate, a non-SU request would
+ * fall through the standard flow and be allowed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOperations = buildOperations;
+const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const hdbError_ts_1 = require("../utility/errors/hdbError.js");
+const session_ts_1 = require("./session.js");
+function buildOperations(deps) {
+    return [
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.AGENT_PROMPT,
+            execute: async (op) => agentPrompt(op, deps),
+        },
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.GET_AGENT_SESSION,
+            execute: async (op) => getAgentSession(op),
+        },
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.LIST_AGENT_SESSIONS,
+            execute: async (op) => listAgentSessions(op),
+        },
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.CANCEL_AGENT_RUN,
+            execute: async (op) => cancelAgentRun(op, deps),
+        },
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.APPROVE_AGENT_ACTION,
+            execute: async (op) => approveAgentAction(op, deps),
+        },
+        {
+            name: hdbTerms_ts_1.OPERATIONS_ENUM.SET_AGENT_CONFIG,
+            execute: async (op) => setAgentConfig(op, deps),
+        },
+    ];
+}
+function requireSuperUser(op) {
+    if (!op?.hdb_user?.role?.permission?.super_user) {
+        throw new hdbError_ts_1.ClientError('Agent operations require super_user', 403);
+    }
+}
+async function agentPrompt(op, deps) {
+    requireSuperUser(op);
+    const config = deps.getConfig();
+    if (!config.enabled) {
+        throw new hdbError_ts_1.ClientError('Agent component is disabled (agent.enabled=false)', 409);
+    }
+    const message = String(op?.message ?? '').trim();
+    if (!message)
+        throw new hdbError_ts_1.ClientError('message is required', 400);
+    let sessionId = op?.session_id;
+    if (sessionId) {
+        const existing = await (0, session_ts_1.getSession)(sessionId);
+        if (!existing)
+            throw new hdbError_ts_1.ClientError(`Unknown session ${sessionId}`, 404);
+        if (existing.status === 'running' || existing.status === 'awaiting_approval') {
+            throw new hdbError_ts_1.ClientError(`Session ${sessionId} is ${existing.status}; resolve or cancel before sending another prompt`, 409);
+        }
+        await (0, session_ts_1.appendMessage)(sessionId, asUserMessage(message));
+    }
+    else {
+        const created = await (0, session_ts_1.createSession)({
+            user: op?.hdb_user?.username ?? config.user,
+            model: config.model,
+            provider: config.provider,
+            initialMessage: asUserMessage(message),
+        });
+        sessionId = created.session_id;
+    }
+    deps.startRun(sessionId);
+    return { session_id: sessionId, status: 'running' };
+}
+async function getAgentSession(op) {
+    requireSuperUser(op);
+    const sessionId = String(op?.session_id ?? '');
+    if (!sessionId)
+        throw new hdbError_ts_1.ClientError('session_id is required', 400);
+    const session = await (0, session_ts_1.getSession)(sessionId);
+    if (!session)
+        throw new hdbError_ts_1.ClientError(`Unknown session ${sessionId}`, 404);
+    return session;
+}
+async function listAgentSessions(op) {
+    requireSuperUser(op);
+    const limit = Number.isFinite(op?.limit) ? Number(op.limit) : undefined;
+    return { sessions: await (0, session_ts_1.listSessions)({ limit }) };
+}
+async function cancelAgentRun(op, deps) {
+    requireSuperUser(op);
+    const sessionId = String(op?.session_id ?? '');
+    if (!sessionId)
+        throw new hdbError_ts_1.ClientError('session_id is required', 400);
+    const session = await (0, session_ts_1.getSession)(sessionId);
+    if (!session)
+        throw new hdbError_ts_1.ClientError(`Unknown session ${sessionId}`, 404);
+    // Abort any active controller (best-effort — there may not be one if the loop is paused
+    // in `awaiting_approval` or sitting `idle` between turns). Always update the persisted
+    // status so a paused session can still be terminated by the operator.
+    const signalledLiveRun = deps.cancelRun(sessionId);
+    const wasTerminal = session.status === 'completed' || session.status === 'aborted' || session.status === 'error';
+    if (!wasTerminal)
+        await (0, session_ts_1.setStatus)(sessionId, 'aborted', 'Cancelled by operator');
+    return { cancelled: !wasTerminal, signalledLiveRun };
+}
+async function approveAgentAction(op, deps) {
+    requireSuperUser(op);
+    const sessionId = String(op?.session_id ?? '');
+    const approvalId = String(op?.approval_id ?? '');
+    if (!sessionId || !approvalId) {
+        throw new hdbError_ts_1.ClientError('session_id and approval_id are required', 400);
+    }
+    const approved = op?.approved !== false;
+    const resolved = await (0, session_ts_1.resolveApproval)(sessionId, approvalId, approved);
+    // Either decision should resume the loop: an approval means execute the saved tool call;
+    // a denial means hand the operator-rejection observation back to the model so it can adjust.
+    deps.startRun(sessionId);
+    return resolved;
+}
+async function setAgentConfig(op, deps) {
+    requireSuperUser(op);
+    const patch = {};
+    for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
+        if (op?.[key] !== undefined)
+            patch[key] = op[key];
+    }
+    return deps.setConfig(patch);
+}
+function asUserMessage(content) {
+    return { role: 'user', content, createdAt: Date.now() };
+}
+//# sourceMappingURL=operations.js.map

package/dist/agent/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../agent/operations.ts"],"names":[],"mappings":"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"}

package/dist/agent/session.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in agent session storage. Backed by `system.hdb_agent_session` so
+ * transcripts and pending approvals survive restarts. The exported helpers
+ * are async to keep the surface uniform — once the underlying store gains
+ * non-blocking paths the call sites won't have to change.
+ *
+ * Intentionally separate from #511's `ConversationResource`: that primitive
+ * is app-facing (per-tenant, multi-user, user-defined schema) while this
+ * table is server-local and operator-owned.
+ */
+import type { AgentMessage, AgentRunStatus, AgentSessionRow, ApprovalRequest } from './types.ts';
+export declare function getAgentSessionTable(): any;
+export interface CreateSessionOpts {
+    sessionId?: string;
+    user: string;
+    model?: string;
+    provider?: string;
+    initialMessage?: AgentMessage;
+}
+export declare function createSession(opts: CreateSessionOpts): Promise<AgentSessionRow>;
+export declare function getSession(sessionId: string): Promise<AgentSessionRow | undefined>;
+export declare function listSessions(opts?: {
+    limit?: number;
+}): Promise<AgentSessionRow[]>;
+export declare function appendMessage(sessionId: string, message: AgentMessage): Promise<AgentSessionRow>;
+export declare function setStatus(sessionId: string, status: AgentRunStatus, lastError?: string): Promise<AgentSessionRow>;
+export declare function addPendingApproval(sessionId: string, approval: Omit<ApprovalRequest, 'id' | 'createdAt'>): Promise<ApprovalRequest>;
+export declare function markApprovalConsumed(sessionId: string, approvalId: string): Promise<void>;
+export declare function resolveApproval(sessionId: string, approvalId: string, approved: boolean): Promise<ApprovalRequest>;
+/**
+ * Reset the cached table reference. Test-only seam; production code lets the
+ * lazy-getter initialize once per process.
+ */
+export declare function _resetForTests(): void;
+/** Inject a mock table accessor for unit tests. Pass `undefined` to restore the lazy default. */
+export declare function _setTableForTests(mock: any): void;

package/dist/agent/session.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Built-in agent session storage. Backed by `system.hdb_agent_session` so
+ * transcripts and pending approvals survive restarts. The exported helpers
+ * are async to keep the surface uniform — once the underlying store gains
+ * non-blocking paths the call sites won't have to change.
+ *
+ * Intentionally separate from #511's `ConversationResource`: that primitive
+ * is app-facing (per-tenant, multi-user, user-defined schema) while this
+ * table is server-local and operator-owned.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentSessionTable = getAgentSessionTable;
+exports.createSession = createSession;
+exports.getSession = getSession;
+exports.listSessions = listSessions;
+exports.appendMessage = appendMessage;
+exports.setStatus = setStatus;
+exports.addPendingApproval = addPendingApproval;
+exports.markApprovalConsumed = markApprovalConsumed;
+exports.resolveApproval = resolveApproval;
+exports._resetForTests = _resetForTests;
+exports._setTableForTests = _setTableForTests;
+const node_crypto_1 = require("node:crypto");
+const databases_ts_1 = require("../resources/databases.js");
+const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+let cachedTable;
+function getAgentSessionTable() {
+    if (cachedTable)
+        return cachedTable;
+    cachedTable = (0, databases_ts_1.table)({
+        table: hdbTerms_ts_1.SYSTEM_TABLE_NAMES.AGENT_SESSION_TABLE_NAME,
+        database: hdbTerms_ts_1.SYSTEM_SCHEMA_NAME,
+        audit: true,
+        trackDeletes: false,
+        attributes: [
+            { name: 'session_id', isPrimaryKey: true },
+            { name: 'user', type: 'string', indexed: true },
+            { name: 'status', type: 'string', indexed: true },
+            { name: 'messages' },
+            { name: 'pendingApprovals' },
+            { name: 'model', type: 'string' },
+            { name: 'provider', type: 'string' },
+            { name: 'createdAt', type: 'number', indexed: true },
+            { name: 'updatedAt', type: 'number', indexed: true },
+            { name: 'lastError', type: 'string' },
+        ],
+    });
+    return cachedTable;
+}
+async function createSession(opts) {
+    const now = Date.now();
+    const row = {
+        session_id: opts.sessionId ?? (0, node_crypto_1.randomUUID)(),
+        user: opts.user,
+        status: 'idle',
+        messages: opts.initialMessage ? [opts.initialMessage] : [],
+        pendingApprovals: [],
+        model: opts.model,
+        provider: opts.provider,
+        createdAt: now,
+        updatedAt: now,
+    };
+    await getAgentSessionTable().primaryStore.put(row.session_id, row);
+    return row;
+}
+async function getSession(sessionId) {
+    return getAgentSessionTable().primaryStore.get(sessionId);
+}
+async function listSessions(opts = {}) {
+    const limit = opts.limit ?? 100;
+    const out = [];
+    for (const entry of getAgentSessionTable().primaryStore.getRange({ reverse: true, limit })) {
+        if (entry.value)
+            out.push(entry.value);
+    }
+    return out;
+}
+/**
+ * Per-session mutation lock. Each row mutation is a read-modify-write against the table; without
+ * serialization, two concurrent mutations on the same session (e.g. the loop appending an assistant
+ * message while the operator resolves an approval) both read the same row and the second `put`
+ * clobbers the first — a lost update. This chains all mutations for a given session id so they
+ * apply sequentially. Reads (`getSession`/`listSessions`) intentionally don't take the lock.
+ */
+const sessionLocks = new Map();
+function withSessionLock(sessionId, fn) {
+    const prev = (sessionLocks.get(sessionId) ?? Promise.resolve()).catch(() => { });
+    const result = prev.then(() => fn());
+    const tail = result.catch(() => { });
+    sessionLocks.set(sessionId, tail);
+    void tail.then(() => {
+        if (sessionLocks.get(sessionId) === tail)
+            sessionLocks.delete(sessionId);
+    });
+    return result;
+}
+function appendMessage(sessionId, message) {
+    return withSessionLock(sessionId, async () => {
+        const session = await requireSession(sessionId);
+        session.messages.push(message);
+        session.updatedAt = Date.now();
+        await getAgentSessionTable().primaryStore.put(sessionId, session);
+        return session;
+    });
+}
+function setStatus(sessionId, status, lastError) {
+    return withSessionLock(sessionId, async () => {
+        const session = await requireSession(sessionId);
+        session.status = status;
+        session.lastError = lastError;
+        session.updatedAt = Date.now();
+        await getAgentSessionTable().primaryStore.put(sessionId, session);
+        return session;
+    });
+}
+function addPendingApproval(sessionId, approval) {
+    return withSessionLock(sessionId, async () => {
+        const session = await requireSession(sessionId);
+        const entry = { ...approval, id: (0, node_crypto_1.randomUUID)(), createdAt: Date.now() };
+        session.pendingApprovals.push(entry);
+        session.status = 'awaiting_approval';
+        session.updatedAt = Date.now();
+        await getAgentSessionTable().primaryStore.put(sessionId, session);
+        return entry;
+    });
+}
+function markApprovalConsumed(sessionId, approvalId) {
+    return withSessionLock(sessionId, async () => {
+        const session = await requireSession(sessionId);
+        const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+        if (!entry)
+            throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+        if (!entry.resolved)
+            throw new Error(`Approval ${approvalId} not yet resolved`);
+        if (entry.consumed)
+            return;
+        entry.consumed = true;
+        session.updatedAt = Date.now();
+        await getAgentSessionTable().primaryStore.put(sessionId, session);
+    });
+}
+function resolveApproval(sessionId, approvalId, approved) {
+    return withSessionLock(sessionId, async () => {
+        const session = await requireSession(sessionId);
+        const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+        if (!entry)
+            throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+        if (entry.resolved)
+            throw new Error(`Approval ${approvalId} already resolved`);
+        entry.resolved = true;
+        entry.approved = approved;
+        entry.resolvedAt = Date.now();
+        // Either decision (approve or deny) returns the session to a resumable `idle` state so the
+        // loop can run again and deliver the resulting observation to the model. Operators who want
+        // to terminate the whole run should use `cancel_agent_run` instead of denying.
+        if (!session.pendingApprovals.some((a) => !a.resolved)) {
+            session.status = 'idle';
+        }
+        session.updatedAt = Date.now();
+        await getAgentSessionTable().primaryStore.put(sessionId, session);
+        return entry;
+    });
+}
+async function requireSession(sessionId) {
+    const session = await getSession(sessionId);
+    if (!session)
+        throw new Error(`No agent session ${sessionId}`);
+    return session;
+}
+/**
+ * Reset the cached table reference. Test-only seam; production code lets the
+ * lazy-getter initialize once per process.
+ */
+function _resetForTests() {
+    cachedTable = undefined;
+}
+/** Inject a mock table accessor for unit tests. Pass `undefined` to restore the lazy default. */
+function _setTableForTests(mock) {
+    cachedTable = mock;
+}
+//# sourceMappingURL=session.js.map

package/dist/agent/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../agent/session.ts"],"names":[],"mappings":"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"}

package/dist/agent/tools/fsTools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Operator-only filesystem tools for the built-in agent (#626).
+ *
+ * Every path is resolved against the configured scopes (componentsRoot,
+ * logDir, configDir) and rejected if it escapes them. Writes are restricted
+ * to `componentsRoot` — `logDir` and `configDir` are observation-only so
+ * the agent can read logs and inspect config without rewriting either.
+ *
+ * Lifted in spirit from the external `harper-agent` CLI's file tools; the
+ * sandboxing rules are tightened here because the in-process agent can
+ * reach more of the filesystem than a remote CLI.
+ */
+import type { AgentTool } from '../types.ts';
+export declare const readFileTool: AgentTool;
+export declare const writeFileTool: AgentTool;
+export declare const listDirTool: AgentTool;
+export declare const grepFilesTool: AgentTool;
+export declare const tailFileTool: AgentTool;
+export declare const fsTools: AgentTool[];