@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/dist/agent/tools/fsTools.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fsTools = exports.tailFileTool = exports.grepFilesTool = exports.listDirTool = exports.writeFileTool = exports.readFileTool = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const MAX_READ_BYTES = 5 * 1024 * 1024; // 5 MiB
+const MAX_WRITE_BYTES = 5 * 1024 * 1024;
+const MAX_GREP_RESULTS = 500;
+const MAX_PATTERN_LENGTH = 1000;
+const DEFAULT_TAIL_LINES = 200;
+const TAIL_READ_BYTES = 1 * 1024 * 1024; // 1 MiB — enough for thousands of normal log lines
+async function resolveScoped(scopes, path, access) {
+    const absolute = (0, node_path_1.resolve)(path);
+    const candidates = [scopes.componentsRoot];
+    if (access === 'read') {
+        candidates.push(scopes.logDir, scopes.configDir);
+    }
+    // Reject a symlink leaf. `safeRealPath` resolves existing symlinks via `realpath` (so a link to
+    // an out-of-scope *existing* file is caught by the isInside check below) — but a link whose
+    // target does NOT exist makes `realpath` throw, and the fallback returns the link's own in-scope
+    // path. `writeFile`/`readFile` then follow the link out of scope. An explicit lstat closes that
+    // gap: a legitimate component/log/config file is never a symlink.
+    try {
+        const linkStat = await (0, promises_1.lstat)(absolute);
+        if (linkStat.isSymbolicLink()) {
+            throw new Error(`Refusing to ${access} through a symlink: ${path}`);
+        }
+    }
+    catch (err) {
+        // ENOENT (path doesn't exist yet — normal for a new-file write) is fine; rethrow anything else
+        // (including our own symlink rejection).
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const realAbsolute = await safeRealPath(absolute);
+    for (const root of candidates) {
+        const realRoot = await safeRealPath(root);
+        if (isInside(realAbsolute, realRoot))
+            return realAbsolute;
+    }
+    throw new Error(`Path is outside the agent's ${access} scope: ${path}`);
+}
+async function safeRealPath(p) {
+    try {
+        return await (0, promises_1.realpath)(p);
+    }
+    catch {
+        // Missing leaf is fine — resolve the deepest existing ancestor and join.
+        const parent = (0, node_path_1.dirname)(p);
+        if (parent === p)
+            return p;
+        const parentReal = await safeRealPath(parent);
+        return (0, node_path_1.resolve)(parentReal, p.slice(parent.length + 1));
+    }
+}
+function isInside(child, parent) {
+    const rel = (0, node_path_1.relative)(parent, child);
+    // On Windows, `path.relative` returns an absolute path when the two arguments are on
+    // different drive letters (e.g. C:\components vs D:\etc). Without this check the agent
+    // could escape its scope by naming a path on another drive.
+    if ((0, node_path_1.isAbsolute)(rel))
+        return false;
+    return rel === '' || (!rel.startsWith('..') && !rel.includes(`..${node_path_1.sep}`));
+}
+exports.readFileTool = {
+    def: {
+        name: 'read_file',
+        description: 'Read a UTF-8 text file within componentsRoot, logDir, or configDir.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute filesystem path.' },
+            },
+            required: ['path'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const path = await resolveScoped(ctx.scopes, args.path, 'read');
+        const st = await (0, promises_1.stat)(path);
+        if (st.size > MAX_READ_BYTES) {
+            throw new Error(`File ${path} exceeds ${MAX_READ_BYTES}-byte read cap (size ${st.size})`);
+        }
+        const content = await (0, promises_1.readFile)(path, 'utf8');
+        return { path, size: st.size, content };
+    },
+};
+exports.writeFileTool = {
+    def: {
+        name: 'write_file',
+        description: 'Write a UTF-8 text file within componentsRoot. Creates parent directories as needed.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute filesystem path under componentsRoot.' },
+                content: { type: 'string', description: 'UTF-8 file contents.' },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const content = String(args.content ?? '');
+        if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES) {
+            throw new Error(`Write exceeds ${MAX_WRITE_BYTES}-byte cap`);
+        }
+        const path = await resolveScoped(ctx.scopes, args.path, 'write');
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(path), { recursive: true });
+        await (0, promises_1.writeFile)(path, content, 'utf8');
+        return { path, bytesWritten: Buffer.byteLength(content, 'utf8') };
+    },
+    destructive: true,
+};
+exports.listDirTool = {
+    def: {
+        name: 'list_dir',
+        description: 'List the immediate entries in a directory within an allowed scope.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute filesystem path.' },
+            },
+            required: ['path'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const path = await resolveScoped(ctx.scopes, args.path, 'read');
+        const entries = await (0, promises_1.readdir)(path, { withFileTypes: true });
+        return {
+            path,
+            entries: entries.map((e) => ({
+                name: e.name,
+                kind: e.isDirectory() ? 'directory' : e.isFile() ? 'file' : 'other',
+            })),
+        };
+    },
+};
+exports.grepFilesTool = {
+    def: {
+        name: 'grep_files',
+        description: 'Search recursively under a scoped directory for a regex pattern. Returns matched lines.',
+        parameters: {
+            type: 'object',
+            properties: {
+                root: { type: 'string', description: 'Directory to search under.' },
+                pattern: { type: 'string', description: 'JavaScript-compatible regular expression source.' },
+                flags: { type: 'string', description: 'Regex flags (default: "i").' },
+                maxResults: { type: 'integer', minimum: 1, maximum: MAX_GREP_RESULTS },
+            },
+            required: ['root', 'pattern'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const root = await resolveScoped(ctx.scopes, args.root, 'read');
+        // Cap pattern length. A maliciously crafted regex (e.g. nested quantifiers) can backtrack
+        // catastrophically and block the main thread; JS has no native per-match timeout. The agent
+        // is super_user-gated so this is self-inflicted DoS rather than a privilege boundary, but a
+        // length cap removes the easiest footgun without a worker-thread regex sandbox.
+        const patternSource = String(args.pattern ?? '');
+        if (patternSource.length > MAX_PATTERN_LENGTH) {
+            throw new Error(`grep pattern exceeds ${MAX_PATTERN_LENGTH}-char cap`);
+        }
+        const pattern = new RegExp(patternSource, args.flags ?? 'i');
+        const cap = Math.min(args.maxResults ?? MAX_GREP_RESULTS, MAX_GREP_RESULTS);
+        const results = [];
+        await walk(root, async (file) => {
+            if (results.length >= cap)
+                return false;
+            // `stat` first so a multi-GB log or database file can't be slurped into memory by a
+            // well-formed grep request. Anything over the read cap is silently skipped.
+            let size = 0;
+            try {
+                const st = await (0, promises_1.stat)(file);
+                size = st.size;
+            }
+            catch {
+                return true;
+            }
+            if (size > MAX_READ_BYTES)
+                return true;
+            const text = await (0, promises_1.readFile)(file, 'utf8').catch(() => '');
+            if (!text)
+                return true;
+            const lines = text.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (results.length >= cap)
+                    return false;
+                if (pattern.test(lines[i]))
+                    results.push({ path: file, line: i + 1, text: lines[i] });
+            }
+            return true;
+        });
+        return { root, count: results.length, results };
+    },
+};
+exports.tailFileTool = {
+    def: {
+        name: 'tail_file',
+        description: 'Return the last N lines of a UTF-8 file. Useful for log tails.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute filesystem path.' },
+                lines: { type: 'integer', minimum: 1, maximum: 5000 },
+            },
+            required: ['path'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const path = await resolveScoped(ctx.scopes, args.path, 'read');
+        const wanted = Math.min(args.lines ?? DEFAULT_TAIL_LINES, 5000);
+        // Read only the trailing TAIL_READ_BYTES — a multi-GB log file otherwise OOMs the process.
+        const st = await (0, promises_1.stat)(path);
+        const start = Math.max(0, st.size - TAIL_READ_BYTES);
+        const truncated = start > 0;
+        const fh = await (0, promises_1.open)(path, 'r');
+        try {
+            const buf = Buffer.alloc(st.size - start);
+            await fh.read(buf, 0, buf.length, start);
+            const text = buf.toString('utf8');
+            const all = text.split('\n');
+            // `split('\n')` on a file ending with `\n` leaves a trailing empty entry — drop it so the
+            // "last N lines" the agent sees matches what a human reading the file would see.
+            if (all.length > 0 && all[all.length - 1] === '')
+                all.pop();
+            // When we read from a mid-file offset the first "line" is almost certainly a partial
+            // fragment of a real line. Drop it so we don't hand the agent a misleading prefix.
+            if (truncated && all.length > 0)
+                all.shift();
+            const sliceStart = Math.max(0, all.length - wanted);
+            return { path, lines: all.slice(sliceStart), truncated };
+        }
+        finally {
+            await fh.close();
+        }
+    },
+};
+exports.fsTools = [exports.readFileTool, exports.writeFileTool, exports.listDirTool, exports.grepFilesTool, exports.tailFileTool];
+async function walk(root, visit) {
+    // Resolve the scope root once via realpath so the per-entry symlink check below has a
+    // stable comparison anchor; otherwise a symlink in the root itself could shift the anchor.
+    const realRoot = await safeRealPath(root);
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = (0, node_path_1.resolve)(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                // Re-resolve via realpath so a symlinked directory pointing outside the scope is rejected.
+                // Without this, `componentsRoot/escape -> /etc` would let grep walk into /etc.
+                const realFull = await safeRealPath(full);
+                if (!isInside(realFull, realRoot))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const realFull = await safeRealPath(full);
+                if (!isInside(realFull, realRoot))
+                    continue;
+                const proceed = await visit(full);
+                if (proceed === false)
+                    return;
+            }
+        }
+    }
+}
+//# sourceMappingURL=fsTools.js.map

package/dist/agent/tools/fsTools.js.map

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

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

@@ -0,0 +1,9 @@
+/**
+ * `http_fetch` for the built-in agent (#626). Wraps the platform `fetch`
+ * with a size cap, an inactivity timeout, and a metadata/loopback blocklist
+ * so the agent can probe its own deployed components and pull lightweight
+ * web pages for context without becoming an SSRF vector against cloud
+ * instance-metadata endpoints or unrelated internal services.
+ */
+import type { AgentTool } from '../types.ts';
+export declare const httpFetchTool: AgentTool;

package/dist/agent/tools/httpFetchTool.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * `http_fetch` for the built-in agent (#626). Wraps the platform `fetch`
+ * with a size cap, an inactivity timeout, and a metadata/loopback blocklist
+ * so the agent can probe its own deployed components and pull lightweight
+ * web pages for context without becoming an SSRF vector against cloud
+ * instance-metadata endpoints or unrelated internal services.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFetchTool = void 0;
+const node_net_1 = require("node:net");
+const MAX_BYTES = 2 * 1024 * 1024; // 2 MiB cap on response bodies
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Hard-blocked literal hosts. Cloud-metadata services live on these IPs and exposing them
+// to a prompt-controlled fetch is a credential-leak vector. Loopback to the local Harper
+// instance is allowed via `localhost`/`127.0.0.1` for self-testing — those are NOT blocked.
+const BLOCKED_HOSTS = new Set([
+    '169.254.169.254', // AWS / GCP / Azure IMDS
+    'fd00:ec2::254', // AWS IMDSv2 IPv6
+    'metadata.google.internal',
+    'metadata.goog',
+]);
+exports.httpFetchTool = {
+    def: {
+        name: 'http_fetch',
+        description: "Issue an HTTP request from the Harper server. Useful for hitting the agent's own components on localhost and pulling reference pages.",
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Absolute URL.' },
+                method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] },
+                headers: { type: 'object', additionalProperties: { type: 'string' } },
+                body: { type: 'string', description: 'Request body as a string (JSON or form-encoded).' },
+                timeoutMs: { type: 'integer', minimum: 1, maximum: 120_000 },
+            },
+            required: ['url'],
+        },
+    },
+    handler: async (args, ctx) => {
+        const url = String(args.url ?? '');
+        if (!/^https?:\/\//i.test(url))
+            throw new Error('http_fetch requires an http(s) URL');
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error(`http_fetch could not parse URL: ${url}`);
+        }
+        const host = parsed.hostname.toLowerCase();
+        if (BLOCKED_HOSTS.has(host)) {
+            throw new Error(`http_fetch blocked by metadata-host policy: ${host}`);
+        }
+        // IPv4 link-local (169.254.0.0/16) covers IMDS variants beyond the canonical 169.254.169.254.
+        if ((0, node_net_1.isIP)(host) === 4 && host.startsWith('169.254.')) {
+            throw new Error(`http_fetch blocked by link-local policy: ${host}`);
+        }
+        const timeoutMs = Math.min(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, 120_000);
+        const localAbort = new AbortController();
+        const timer = setTimeout(() => localAbort.abort(new Error(`http_fetch timed out after ${timeoutMs}ms`)), timeoutMs);
+        const signal = combineSignals(ctx.signal, localAbort.signal);
+        try {
+            const response = await fetch(url, {
+                method: args.method ?? 'GET',
+                headers: args.headers,
+                body: args.body,
+                signal,
+            });
+            const buffer = await readCapped(response, MAX_BYTES);
+            return {
+                status: response.status,
+                headers: Object.fromEntries(response.headers.entries()),
+                body: buffer.toString('utf8'),
+                truncated: buffer.length === MAX_BYTES,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+};
+async function readCapped(response, cap) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    while (total < cap) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        const chunk = Buffer.from(value);
+        const room = cap - total;
+        if (chunk.length > room) {
+            chunks.push(chunk.subarray(0, room));
+            total += room;
+            await reader.cancel().catch(() => { });
+            break;
+        }
+        chunks.push(chunk);
+        total += chunk.length;
+    }
+    return Buffer.concat(chunks, total);
+}
+function combineSignals(...signals) {
+    const present = signals.filter((s) => Boolean(s));
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    // `AbortSignal.any` (Node 20+) manages listener cleanup internally; the manual
+    // `addEventListener` approach leaked listeners on `ctx.signal` for the lifetime of the agent
+    // run when a fetch completed normally.
+    return AbortSignal.any(present);
+}
+//# sourceMappingURL=httpFetchTool.js.map

package/dist/agent/tools/httpFetchTool.js.map

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

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

@@ -0,0 +1,22 @@
+/**
+ * `schedule_followup` for the built-in agent (#626).
+ *
+ * Lives on the main thread so it survives worker-thread restarts that happen
+ * on code reload. The followup callback is injected from the entry point —
+ * this module only schedules the timer and tracks pending entries.
+ */
+import type { AgentTool } from '../types.ts';
+export interface ScheduledFollowup {
+    id: string;
+    sessionId: string;
+    prompt: string;
+    fireAt: number;
+    timer: NodeJS.Timeout;
+}
+export interface ScheduleToolDeps {
+    onFollowup: (sessionId: string, prompt: string) => Promise<void> | void;
+}
+export declare function buildScheduleTool(deps: ScheduleToolDeps): {
+    tool: AgentTool;
+    pending: Map<string, ScheduledFollowup>;
+};

package/dist/agent/tools/scheduleTool.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * `schedule_followup` for the built-in agent (#626).
+ *
+ * Lives on the main thread so it survives worker-thread restarts that happen
+ * on code reload. The followup callback is injected from the entry point —
+ * this module only schedules the timer and tracks pending entries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildScheduleTool = buildScheduleTool;
+const node_crypto_1 = require("node:crypto");
+const MAX_DELAY_MS = 24 * 60 * 60 * 1000; // 24h
+const MIN_DELAY_MS = 1_000;
+function buildScheduleTool(deps) {
+    const pending = new Map();
+    const tool = {
+        def: {
+            name: 'schedule_followup',
+            description: 'Re-invoke the agent on the current session after the given delay with a new prompt.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    delayMs: { type: 'integer', minimum: MIN_DELAY_MS, maximum: MAX_DELAY_MS },
+                    prompt: { type: 'string', description: 'Prompt the agent should re-enter on with.' },
+                },
+                required: ['delayMs', 'prompt'],
+            },
+        },
+        handler: async (args, ctx) => {
+            const delay = Number(args.delayMs);
+            if (!Number.isFinite(delay) || delay < MIN_DELAY_MS || delay > MAX_DELAY_MS) {
+                throw new Error(`delayMs must be between ${MIN_DELAY_MS} and ${MAX_DELAY_MS}`);
+            }
+            const prompt = String(args.prompt ?? '').trim();
+            if (!prompt)
+                throw new Error('prompt is required');
+            const id = (0, node_crypto_1.randomUUID)();
+            const fireAt = Date.now() + delay;
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                Promise.resolve()
+                    .then(() => deps.onFollowup(ctx.sessionId, prompt))
+                    .catch(() => {
+                    /* swallow — caller logs */
+                });
+            }, delay);
+            timer.unref?.();
+            pending.set(id, { id, sessionId: ctx.sessionId, prompt, fireAt, timer });
+            return { id, fireAt };
+        },
+    };
+    return { tool, pending };
+}
+//# sourceMappingURL=scheduleTool.js.map

package/dist/agent/tools/scheduleTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduleTool.js","sourceRoot":"","sources":["../../../agent/tools/scheduleTool.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAoBH,8CAyCC;AA3DD,6CAAyC;AAGzC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM;AAChD,MAAM,YAAY,GAAG,KAAK,CAAC;AAc3B,SAAgB,iBAAiB,CAAC,IAAsB;IAIvD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IACrD,MAAM,IAAI,GAAc;QACvB,GAAG,EAAE;YACJ,IAAI,EAAE,mBAAmB;YACzB,WAAW,EAAE,qFAAqF;YAClG,UAAU,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACX,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE;oBAC1E,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAAE;iBACpF;gBACD,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;aAC/B;SACD;QACD,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,GAAqB,EAAE,EAAE;YACnD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,YAAY,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;gBAC7E,MAAM,IAAI,KAAK,CAAC,2BAA2B,YAAY,QAAQ,YAAY,EAAE,CAAC,CAAC;YAChF,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAChD,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACnD,MAAM,EAAE,GAAG,IAAA,wBAAU,GAAE,CAAC;YACxB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;YAClC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC7B,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACnB,OAAO,CAAC,OAAO,EAAE;qBACf,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;qBAClD,KAAK,CAAC,GAAG,EAAE;oBACX,2BAA2B;gBAC5B,CAAC,CAAC,CAAC;YACL,CAAC,EAAE,KAAK,CAAC,CAAC;YACV,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YACzE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QACvB,CAAC;KACD,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC1B,CAAC"}

package/dist/agent/toolset.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tool composer for the built-in agent (#626).
+ *
+ * Operator-only tools (FS, schedule, fetch) are inline today. Once the
+ * unified MCP tool registry (#615) lands with the Operations (#617) and
+ * Application (#618) profiles, this is the seam where RBAC-filtered
+ * registry tools get folded in for the agent's configured user. The shape
+ * of {@link composeToolset} won't change — only the body gains a registry
+ * lookup.
+ */
+import { type ScheduleToolDeps, type ScheduledFollowup } from './tools/scheduleTool.ts';
+import type { AgentTool } from './types.ts';
+export interface ComposeToolsetOpts extends ScheduleToolDeps {
+    /** When `false`, destructive tools are filtered out at composition time. */
+    allowDestructive?: boolean;
+    /** Operator-injected extras (tests, custom plugins). */
+    extraTools?: AgentTool[];
+}
+export interface ComposedToolset {
+    tools: AgentTool[];
+    scheduled: Map<string, ScheduledFollowup>;
+}
+export declare function composeToolset(opts: ComposeToolsetOpts): ComposedToolset;
+export declare function toolMapByName(tools: AgentTool[]): Map<string, AgentTool>;

package/dist/agent/toolset.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Tool composer for the built-in agent (#626).
+ *
+ * Operator-only tools (FS, schedule, fetch) are inline today. Once the
+ * unified MCP tool registry (#615) lands with the Operations (#617) and
+ * Application (#618) profiles, this is the seam where RBAC-filtered
+ * registry tools get folded in for the agent's configured user. The shape
+ * of {@link composeToolset} won't change — only the body gains a registry
+ * lookup.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeToolset = composeToolset;
+exports.toolMapByName = toolMapByName;
+const fsTools_ts_1 = require("./tools/fsTools.js");
+const httpFetchTool_ts_1 = require("./tools/httpFetchTool.js");
+const scheduleTool_ts_1 = require("./tools/scheduleTool.js");
+function composeToolset(opts) {
+    const schedule = (0, scheduleTool_ts_1.buildScheduleTool)(opts);
+    const all = [...fsTools_ts_1.fsTools, httpFetchTool_ts_1.httpFetchTool, schedule.tool, ...(opts.extraTools ?? [])];
+    const tools = opts.allowDestructive === false ? all.filter((t) => !t.destructive) : all;
+    return { tools, scheduled: schedule.pending };
+}
+function toolMapByName(tools) {
+    const map = new Map();
+    for (const tool of tools) {
+        if (map.has(tool.def.name))
+            throw new Error(`Duplicate tool registered: ${tool.def.name}`);
+        map.set(tool.def.name, tool);
+    }
+    return map;
+}
+//# sourceMappingURL=toolset.js.map

package/dist/agent/toolset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset.js","sourceRoot":"","sources":["../../agent/toolset.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAmBH,wCAKC;AAED,sCAOC;AA/BD,mDAA6C;AAC7C,+DAAyD;AACzD,6DAA2G;AAe3G,SAAgB,cAAc,CAAC,IAAwB;IACtD,MAAM,QAAQ,GAAG,IAAA,mCAAiB,EAAC,IAAI,CAAC,CAAC;IACzC,MAAM,GAAG,GAAgB,CAAC,GAAG,oBAAO,EAAE,gCAAa,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;IAChG,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACxF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,SAAgB,aAAa,CAAC,KAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAqB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3F,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/agent/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared types for the built-in Harper Agent component (#626).
+ *
+ * `AgentMessage` mirrors `resources/models/types.ts:Message` rather than
+ * re-exporting it: the session row is durable storage and shouldn't trail
+ * shape changes in the model-access surface.
+ */
+import type { ToolCall, ToolDef } from '../resources/models/types.ts';
+export type AgentRunStatus = 'idle' | 'running' | 'awaiting_approval' | 'completed' | 'aborted' | 'error';
+export interface AgentMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    /** Wall-clock timestamp of when this item entered the transcript. */
+    createdAt: number;
+}
+export interface ApprovalRequest {
+    id: string;
+    toolName: string;
+    arguments: object;
+    /** Tool-call id from the assistant message that produced this request. Used to resume execution. */
+    toolCallId: string;
+    /** Human-readable rationale for why approval is required (e.g. 'destructive', 'first_use'). */
+    reason: string;
+    createdAt: number;
+    resolved?: boolean;
+    approved?: boolean;
+    resolvedAt?: number;
+    /** Set to true once the loop has consumed the resolved approval (executed or refused). */
+    consumed?: boolean;
+}
+export interface AgentSessionRow {
+    session_id: string;
+    user: string;
+    status: AgentRunStatus;
+    messages: AgentMessage[];
+    pendingApprovals: ApprovalRequest[];
+    model?: string;
+    provider?: string;
+    createdAt: number;
+    updatedAt: number;
+    lastError?: string;
+}
+export interface AgentToolHandler {
+    (args: object, ctx: AgentToolContext): Promise<unknown>;
+}
+export interface AgentTool {
+    def: ToolDef;
+    handler: AgentToolHandler;
+    /** When true, invocations of this tool require an approval gate unless `autoApprove` is set. */
+    destructive?: boolean;
+}
+export interface AgentToolContext {
+    sessionId: string;
+    signal?: AbortSignal;
+    /** Filesystem scope roots accessible to FS tools. Read-only after composition. */
+    scopes: AgentScopes;
+}
+export interface AgentScopes {
+    componentsRoot: string;
+    logDir: string;
+    configDir: string;
+}
+export interface AgentConfig {
+    enabled: boolean;
+    provider?: string;
+    model?: string;
+    maxTurns: number;
+    maxCostUsd: number;
+    autoApprove: boolean;
+    allowDestructive: boolean;
+    user: string;
+    componentsScope?: string;
+}