@harperfast/harper 5.0.25 → 5.1.0-beta.1

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[];