@harperfast/harper 5.2.0-alpha.4 → 5.2.0-alpha.6

package/dist/agent/agent.js

@@ -9,22 +9,63 @@
  * is realized lazily on first use, and the loop runs in-process.
  *
  * The component intentionally avoids `handleApplication`: it has nothing
- * worker-thread-shaped to do. Operator-only tools (FS, schedule, fetch) are
- * inline; registry-backed tools (#615/#617/#618) will fold in via toolset.ts
- * once those land.
+ * worker-thread-shaped to do. Two tool sources compose: operator-only tools
+ * (FS, schedule, fetch, and the V8 inspector) that are inline, and RBAC-filtered
+ * registry tools (#615/#617) drained for the agent's configured user via
+ * `registryTools.ts`.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startOnMainThread = startOnMainThread;
+exports.resolveAgentIdentity = resolveAgentIdentity;
 exports._resetForTests = _resetForTests;
 const node_path_1 = require("node:path");
 const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const env = __importStar(require("../utility/environment/environmentManager.js"));
 const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
 const Models_ts_1 = require("../resources/models/Models.js");
+const manageThreads_js_1 = require("../server/threads/manageThreads.js");
 const toolset_ts_1 = require("./toolset.js");
+const inspectorTool_ts_1 = require("./tools/inspectorTool.js");
+const bestPractices_ts_1 = require("./bestPractices.js");
+const registryTools_ts_1 = require("./registryTools.js");
 const operations_ts_1 = require("./operations.js");
+const mcpTools_ts_1 = require("./mcpTools.js");
 const loop_ts_1 = require("./loop.js");
 const session_ts_1 = require("./session.js");
 const log = harper_logger_ts_1.default.loggerWithTag('agent');
@@ -48,10 +89,54 @@ async function startOnMainThread(opts) {
     const models = new Models_ts_1.Models();
     const abortControllers = new Map();
     let liveConfig = config;
-    let composed = (0, toolset_ts_1.composeToolset)({
-        allowDestructive: liveConfig.allowDestructive,
-        onFollowup: handleFollowup,
+    // Populate the Operations MCP profile on the main thread. `agentIdentity` resolves the enforcement
+    // identity fresh on each call (so a live role change is honored, and an unresolvable non-default
+    // user fails closed); the startup snapshot below is only for `visibleTo` listing.
+    (0, registryTools_ts_1.ensureOperationsToolsRegistered)();
+    const agentIdentity = () => resolveAgentIdentity(opts.server, liveConfig.user);
+    let registryTools = await composeRegistryToolsForListing(agentIdentity);
+    // Operator-only V8 inspector tools. Debug config is read once here — enabling threads_debug opens the
+    // worker inspector ports at thread boot, so it can't be toggled without a restart anyway. Worker
+    // count is a live closure over the pool, so attaches range-check against the current worker set.
+    const inspectorTools = (0, inspectorTool_ts_1.buildInspectorTools)({
+        debugEnabled: env.get(hdbTerms_ts_1.CONFIG_PARAMS.THREADS_DEBUG) !== false,
+        startingPort: env.get(hdbTerms_ts_1.CONFIG_PARAMS.THREADS_DEBUG_STARTINGPORT) ?? undefined,
+        host: env.get(hdbTerms_ts_1.CONFIG_PARAMS.THREADS_DEBUG_HOST) ?? '127.0.0.1',
+        getWorkerCount: () => manageThreads_js_1.workers.length,
     });
+    // Harper best-practices skill (@harperfast/skills): the SKILL.md overview goes in the system prompt;
+    // the `harper_best_practice` tool serves the detailed rules on demand. Both degrade to nothing if the
+    // package isn't resolvable, so the agent still runs without it.
+    const bestPracticesOverview = (0, bestPractices_ts_1.loadBestPracticesOverview)();
+    const bestPracticeTool = (0, bestPractices_ts_1.buildBestPracticeTool)();
+    const extraTools = bestPracticeTool ? [bestPracticeTool] : [];
+    // The grounding + best-practices portion of the system prompt is static for the component's
+    // lifetime (scopes don't change), so build it once here; only the operator's per-run
+    // `systemPromptAppend` is folded on at run time in `startRun`.
+    const staticSystemPrompt = buildStaticSystemPrompt(scopes, bestPracticesOverview);
+    function compose() {
+        return (0, toolset_ts_1.composeToolset)({
+            allowDestructive: liveConfig.allowDestructive,
+            onFollowup: handleFollowup,
+            inspectorTools,
+            registryTools,
+            extraTools,
+        });
+    }
+    let composed = compose();
+    // Build the listing snapshot best-effort: if the configured user can't be resolved (and isn't the
+    // default bootstrap user), `agentIdentity` fails closed — the agent then runs with only its
+    // operator-only tools until the operator fixes `agent.user`. Never falls back to an escalated list.
+    async function composeRegistryToolsForListing(resolveIdentity) {
+        try {
+            const listingUser = await resolveIdentity();
+            return (0, registryTools_ts_1.composeRegistryTools)(listingUser, resolveIdentity);
+        }
+        catch (err) {
+            log.error?.(`Registry tools disabled — agent.user='${liveConfig.user}' could not be resolved: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
     // Only warn when the operator explicitly configured `maxCostUsd`. Logging on the default
     // every boot would flood the log without telling anyone anything actionable.
     if (opts.maxCostUsd !== undefined) {
@@ -88,6 +173,7 @@ async function startOnMainThread(opts) {
             autoApprove: liveConfig.autoApprove,
             signal: controller.signal,
             generateOpts: { model: liveConfig.model },
+            systemPrompt: composeSystemPrompt(staticSystemPrompt, liveConfig.systemPromptAppend),
         })
             .catch((err) => log.error?.(`Agent run failed for ${sessionId}: ${err?.message ?? err}`))
             .finally(() => {
@@ -116,10 +202,7 @@ async function startOnMainThread(opts) {
         const previousAllowDestructive = liveConfig.allowDestructive;
         liveConfig = { ...liveConfig, ...patch };
         if (liveConfig.allowDestructive !== previousAllowDestructive) {
-            composed = (0, toolset_ts_1.composeToolset)({
-                allowDestructive: liveConfig.allowDestructive,
-                onFollowup: handleFollowup,
-            });
+            composed = compose();
         }
         // NOTE: an already in-flight run captured its toolset (and autoApprove) at start, so flipping
         // allowDestructive here only affects subsequent runs — the live loop finishes on its existing
@@ -136,8 +219,86 @@ async function startOnMainThread(opts) {
     });
     for (const op of operations)
         opts.server.registerOperation(op);
+    // Expose the agent over MCP: register curated agent tools into the registry AFTER the ops exist.
+    // (The generic operations-profile walk ran before this, so allow-listing the agent ops wouldn't
+    // surface them — see mcpTools.ts.) They only reach clients when the MCP surface is enabled.
+    (0, mcpTools_ts_1.registerAgentMcpTools)(operations);
     log.info?.(`Agent component initialized with ${composed.tools.length} tools`);
 }
+/**
+ * Grounding prompt so the agent knows what it is, where its files live, and how a Harper app is
+ * shaped. The filesystem tools take a `root` scope enum, so we describe the scopes rather than
+ * spelling out path-prefixing rules.
+ *
+ * We deliberately do NOT enumerate individual tool names here — the model already receives the full
+ * tool schema from the SDK, and duplicating names in the prompt drifts as tools are added/removed and
+ * invites hallucinated calls. This describes the tool *surface* at a category level only.
+ *
+ * The built-in grounding and best-practices overview are static for the component's lifetime, so the
+ * caller precomputes them once (`buildStaticSystemPrompt`) and only the operator
+ * `agent.systemPromptAppend` — which can change via `set_agent_config` without a restart — is folded
+ * in per run by `composeSystemPrompt`.
+ */
+function buildStaticSystemPrompt(scopes, bestPracticesOverview) {
+    const parts = [
+        'You are the built-in Harper agent, running on the main thread inside a live Harper server.',
+        'You operate this instance for an operator through the tools provided to you: Harper database/cluster operations, scoped filesystem tools, HTTP fetch against this server, followup scheduling, and (when available) V8 inspector tools for debugging worker threads plus a Harper best-practices lookup. Consult the provided tool schemas for the exact set and their parameters.',
+        '',
+        'Filesystem scopes (the fs tools take a `root` naming one of these; paths are relative to it):',
+        `- components — the app source directory, your only WRITE scope: ${scopes.componentsRoot}`,
+        `- logs — read-only: ${scopes.logDir}`,
+        `- config — read-only: ${scopes.configDir}`,
+        '',
+        'A Harper app is a component directory under the components dir. Define tables/resources in a schema (GraphQL `.graphql` with `@table`/`@export`, or `config.yaml` + resource files). After writing or changing component files, deploy/restart as needed for them to load, then verify by querying the REST endpoint via an HTTP fetch against this server.',
+        'Prefer the operations tools for database/cluster actions; use the filesystem tools for app source. When designing schemas or building app logic, consult the Harper best practices below and read the relevant rule via the best-practice tool. Be concise and verify your work.',
+    ];
+    if (bestPracticesOverview) {
+        parts.push('', '=== Harper best practices (overview) ===', bestPracticesOverview);
+    }
+    return parts.join('\n');
+}
+/** Fold the operator's per-run `systemPromptAppend` onto the precomputed static base. */
+function composeSystemPrompt(staticPrompt, append) {
+    if (typeof append === 'string' && append.trim()) {
+        return `${staticPrompt}\n\n=== Operator instructions ===\n${append.trim()}`;
+    }
+    return staticPrompt;
+}
+/**
+ * Resolve the identity the agent's tool calls run as. Registry tools are enforced
+ * (`hdb_user` at call time) against this user, so an operator who sets `agent.user`
+ * to a restricted role gets a narrowed surface — and a later role change is honored,
+ * because this runs per call rather than once at startup.
+ *
+ * Failure policy — fail closed, with one bounded exception:
+ *   - If `agent.user` resolves to a permissioned user, use it.
+ *   - If it can't be resolved AND it's the *default* `hdb_agent` bootstrap user,
+ *     fall back to a super_user identity (the system user isn't provisioned yet —
+ *     #626 defers creating it). This is the documented default-agent behavior.
+ *   - If it can't be resolved and the operator configured a *non-default* user,
+ *     throw. Silently escalating a misconfigured/transient restricted account to
+ *     super_user is the vulnerability we refuse to introduce.
+ */
+async function resolveAgentIdentity(server, username) {
+    let resolved;
+    if (typeof server.getUser === 'function') {
+        try {
+            const user = await server.getUser(username, null, null);
+            if (user?.role?.permission)
+                resolved = user;
+        }
+        catch (err) {
+            log.warn?.(`Failed to resolve agent.user='${username}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (resolved)
+        return resolved;
+    if (username === DEFAULT_CONFIG.user) {
+        log.warn?.(`Default agent user '${username}' is not provisioned yet; using super_user bootstrap identity`);
+        return { username, role: { permission: { super_user: true } } };
+    }
+    throw new Error(`agent.user '${username}' could not be resolved to a permissioned user; failing closed`);
+}
 function resolveScopes(config, getConfigPath, getConfigFilePath) {
     const componentsRoot = getConfigPath(hdbTerms_ts_1.CONFIG_PARAMS.COMPONENTSROOT) ?? process.cwd();
     const logDir = getConfigPath(hdbTerms_ts_1.CONFIG_PARAMS.LOGGING_ROOT) ?? process.cwd();
@@ -166,6 +327,7 @@ function mergeConfig(opts) {
         ...(opts.allowDestructive !== undefined && { allowDestructive: !!opts.allowDestructive }),
         ...(opts.user !== undefined && { user: String(opts.user) }),
         ...(opts.componentsScope !== undefined && { componentsScope: String(opts.componentsScope) }),
+        ...(opts.systemPromptAppend !== undefined && { systemPromptAppend: String(opts.systemPromptAppend) }),
     };
 }
 /** Test-only: reset module state between specs. */

package/dist/agent/agent.js.map

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

package/dist/agent/bestPractices.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Harper best-practices knowledge for the built-in agent (#626).
+ *
+ * Sources the `harper-best-practices` skill from the `@harperfast/skills`
+ * package (versioned with the release, no drift). The package exposes the skill
+ * content directly as module exports — `skillSummary` (the SKILL.md overview),
+ * `ruleNames` (the rule index), and `rules` (name → markdown body) — so we read
+ * from those rather than groveling around the installed package on disk.
+ *
+ * Progressive disclosure, mirroring how the skill is meant to be used:
+ *   - the SKILL.md overview (rule index + when-to-use) is injected into the
+ *     agent's system prompt so it always knows *which* practices exist;
+ *   - the detailed rule bodies are pulled on demand via the
+ *     `harper_best_practice` tool, so the agent only spends context on the
+ *     guidance relevant to the task instead of carrying all ~20 rules.
+ */
+import type { AgentTool } from './types.ts';
+/** The SKILL.md overview (rule index + guidance), for injection into the system prompt. Undefined if unavailable. */
+export declare function loadBestPracticesOverview(): string | undefined;
+/**
+ * A tool that lists the best-practice rules (no arg) or returns one rule's full body (`rule` arg).
+ * Returns undefined when the skill package ships no rules, so the caller simply omits it.
+ */
+export declare function buildBestPracticeTool(): AgentTool | undefined;

package/dist/agent/bestPractices.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Harper best-practices knowledge for the built-in agent (#626).
+ *
+ * Sources the `harper-best-practices` skill from the `@harperfast/skills`
+ * package (versioned with the release, no drift). The package exposes the skill
+ * content directly as module exports — `skillSummary` (the SKILL.md overview),
+ * `ruleNames` (the rule index), and `rules` (name → markdown body) — so we read
+ * from those rather than groveling around the installed package on disk.
+ *
+ * Progressive disclosure, mirroring how the skill is meant to be used:
+ *   - the SKILL.md overview (rule index + when-to-use) is injected into the
+ *     agent's system prompt so it always knows *which* practices exist;
+ *   - the detailed rule bodies are pulled on demand via the
+ *     `harper_best_practice` tool, so the agent only spends context on the
+ *     guidance relevant to the task instead of carrying all ~20 rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadBestPracticesOverview = loadBestPracticesOverview;
+exports.buildBestPracticeTool = buildBestPracticeTool;
+const skills_1 = require("@harperfast/skills");
+/** The SKILL.md overview (rule index + guidance), for injection into the system prompt. Undefined if unavailable. */
+function loadBestPracticesOverview() {
+    return skills_1.skillSummary || undefined;
+}
+/**
+ * A tool that lists the best-practice rules (no arg) or returns one rule's full body (`rule` arg).
+ * Returns undefined when the skill package ships no rules, so the caller simply omits it.
+ */
+function buildBestPracticeTool() {
+    if (!skills_1.ruleNames?.length)
+        return undefined;
+    return {
+        def: {
+            name: 'harper_best_practice',
+            description: 'Read a Harper best-practices rule for detailed guidance and code examples — schema design, relationships, automatic/REST APIs, authentication, custom resources, caching, vector indexing, TypeScript type-stripping, deployment, logging, and more. Call with no `rule` to list the available rule names; then call again with a `rule` to read it. Consult these before designing schemas or building app logic.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    rule: {
+                        type: 'string',
+                        description: 'Rule name without extension, e.g. "adding-tables-with-schemas". Omit to list all rules.',
+                    },
+                },
+            },
+        },
+        handler: async (args) => {
+            const rule = args?.rule ? String(args.rule).trim() : '';
+            if (!rule)
+                return { rules: [...skills_1.ruleNames] };
+            // A plain map lookup — an unknown or malformed name simply misses, so there's no
+            // path-traversal surface to guard against.
+            const content = skills_1.rules[rule];
+            if (content == null)
+                throw new Error(`No such best-practice rule: '${rule}'. Call with no rule to list available rules.`);
+            return { rule, content };
+        },
+    };
+}
+//# sourceMappingURL=bestPractices.js.map

package/dist/agent/bestPractices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bestPractices.js","sourceRoot":"","sources":["../../agent/bestPractices.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAMH,8DAEC;AAMD,sDA4BC;AAxCD,+CAAoE;AAGpE,qHAAqH;AACrH,SAAgB,yBAAyB;IACxC,OAAO,qBAAY,IAAI,SAAS,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB;IACpC,IAAI,CAAC,kBAAS,EAAE,MAAM;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO;QACN,GAAG,EAAE;YACJ,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACV,oZAAoZ;YACrZ,UAAU,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACX,IAAI,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,yFAAyF;qBACtG;iBACD;aACD;SACD;QACD,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC,IAAI;gBAAE,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,kBAAS,CAAC,EAAE,CAAC;YAC5C,iFAAiF;YACjF,2CAA2C;YAC3C,MAAM,OAAO,GAAI,cAAgC,CAAC,IAAI,CAAC,CAAC;YACxD,IAAI,OAAO,IAAI,IAAI;gBAClB,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,+CAA+C,CAAC,CAAC;YACtG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1B,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/agent/mcpTools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Expose the built-in agent over MCP (#626).
+ *
+ * The generic MCP operations profile (#617) can surface these ops too, but only
+ * when an operator opts them into `mcp.operations.allow` and with generic,
+ * schema-inferred descriptions. We register a *curated* agent tool set directly
+ * into the registry instead: exposed by default (no allow-list entry needed),
+ * with hand-written descriptions and annotations tuned for driving the agent.
+ *
+ * Each tool dispatches through the SAME path the generic operations profile uses
+ * (`makeOperationToolHandler` → `chooseOperation` + `processLocalTransaction`), so
+ * Harper's `verifyPerms` runs at call time and enforces the `requiresSuperUser: true`
+ * declared on each agent op — plus any scoped `operations: ['agent_*']` delegation
+ * role. Listing mirrors that boundary via `canRoleInvokeOperation`. A direct
+ * `op.execute(body)` call is NOT used: it would bypass `verifyPerms` entirely and
+ * let any authenticated MCP user drive the super_user agent.
+ */
+import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
+/**
+ * Register the curated agent tools into the MCP registry (operations profile). Call after the agent
+ * operations are registered. Safe to call whether or not the MCP HTTP surface is enabled — the tools
+ * simply sit in the registry until an MCP client lists them.
+ */
+export declare function registerAgentMcpTools(operations: OperationDefinition[]): void;

package/dist/agent/mcpTools.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Expose the built-in agent over MCP (#626).
+ *
+ * The generic MCP operations profile (#617) can surface these ops too, but only
+ * when an operator opts them into `mcp.operations.allow` and with generic,
+ * schema-inferred descriptions. We register a *curated* agent tool set directly
+ * into the registry instead: exposed by default (no allow-list entry needed),
+ * with hand-written descriptions and annotations tuned for driving the agent.
+ *
+ * Each tool dispatches through the SAME path the generic operations profile uses
+ * (`makeOperationToolHandler` → `chooseOperation` + `processLocalTransaction`), so
+ * Harper's `verifyPerms` runs at call time and enforces the `requiresSuperUser: true`
+ * declared on each agent op — plus any scoped `operations: ['agent_*']` delegation
+ * role. Listing mirrors that boundary via `canRoleInvokeOperation`. A direct
+ * `op.execute(body)` call is NOT used: it would bypass `verifyPerms` entirely and
+ * let any authenticated MCP user drive the super_user agent.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentMcpTools = registerAgentMcpTools;
+const toolRegistry_ts_1 = require("../components/mcp/toolRegistry.js");
+const operations_ts_1 = require("../components/mcp/tools/operations.js");
+const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
+const log = harper_logger_ts_1.default.loggerWithTag('agent');
+// Curated client-facing surface for driving the agent. `set_agent_config` is intentionally excluded
+// — it's an operator/config action, not something an MCP client should reach.
+const AGENT_MCP_TOOLS = {
+    agent_prompt: {
+        description: 'Send a prompt to the built-in Harper agent. Starts a new session, or continues one when session_id is given. Returns { session_id, status }; poll get_agent_session for the transcript and result.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'The instruction/prompt for the agent.' },
+                session_id: { type: 'string', description: 'Optional existing session id to continue the conversation.' },
+            },
+            required: ['message'],
+        },
+        destructive: true, // the agent may take actions in response
+    },
+    get_agent_session: {
+        description: 'Read a built-in-agent session: its status, full transcript (messages, tool calls and results), and any pending approvals.',
+        inputSchema: {
+            type: 'object',
+            properties: { session_id: { type: 'string' } },
+            required: ['session_id'],
+        },
+        readOnly: true,
+    },
+    list_agent_sessions: {
+        description: 'List built-in-agent sessions, most recent first.',
+        inputSchema: {
+            type: 'object',
+            properties: { limit: { type: 'integer', minimum: 1, description: 'Max sessions to return (default 100).' } },
+        },
+        readOnly: true,
+    },
+    approve_agent_action: {
+        description: 'Approve or deny a pending agent tool call (when autoApprove is off), then resume the run. Get the approval_id from get_agent_session.pendingApprovals.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: { type: 'string' },
+                approval_id: { type: 'string' },
+                approved: { type: 'boolean', description: 'true to approve (default), false to deny.' },
+            },
+            required: ['session_id', 'approval_id'],
+        },
+        destructive: true,
+    },
+    cancel_agent_run: {
+        description: 'Cancel an in-progress agent run for a session.',
+        inputSchema: {
+            type: 'object',
+            properties: { session_id: { type: 'string' } },
+            required: ['session_id'],
+        },
+        destructive: true,
+    },
+};
+/**
+ * Register the curated agent tools into the MCP registry (operations profile). Call after the agent
+ * operations are registered. Safe to call whether or not the MCP HTTP surface is enabled — the tools
+ * simply sit in the registry until an MCP client lists them.
+ */
+function registerAgentMcpTools(operations) {
+    const registered = new Set(operations.map((op) => op.name));
+    let count = 0;
+    for (const [name, meta] of Object.entries(AGENT_MCP_TOOLS)) {
+        if (!registered.has(name))
+            continue; // op not registered (shouldn't happen) — skip rather than expose a dead tool
+        const annotations = meta.destructive ? { destructiveHint: true } : meta.readOnly ? { readOnlyHint: true } : {};
+        (0, toolRegistry_ts_1.addTool)({
+            name,
+            description: meta.description,
+            inputSchema: meta.inputSchema,
+            profile: 'operations',
+            ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+            // List only for users the op's role-level policy would let call it (super_user, or a
+            // scoped `operations: ['agent_*']` delegation role). verifyPerms enforces the same at
+            // call time inside makeOperationToolHandler — this predicate keeps hidden tools out of
+            // the listing, not out of reach.
+            visibleTo: (user) => (0, toolRegistry_ts_1.canRoleInvokeOperation)(user, name),
+            // Route through the standard operation dispatch (chooseOperation + processLocalTransaction),
+            // so verifyPerms runs and the op's requiresSuperUser gate is actually enforced — a direct
+            // op.execute() would skip it. Same handler the generic operations profile uses.
+            handler: (0, operations_ts_1.makeOperationToolHandler)(name),
+        });
+        count++;
+    }
+    log.info?.(`Agent MCP tools registered: ${count}`);
+}
+//# sourceMappingURL=mcpTools.js.map

package/dist/agent/mcpTools.js.map

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

package/dist/agent/operations.js

@@ -123,7 +123,16 @@ async function approveAgentAction(op, deps) {
 }
 async function setAgentConfig(op, deps) {
     const patch = {};
-    for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
+    for (const key of [
+        'enabled',
+        'provider',
+        'model',
+        'maxTurns',
+        'maxCostUsd',
+        'autoApprove',
+        'allowDestructive',
+        'systemPromptAppend',
+    ]) {
         if (op?.[key] !== undefined)
             patch[key] = op[key];
     }

package/dist/agent/operations.js.map

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

package/dist/agent/registryTools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Registry tool composition for the built-in agent (#626).
+ *
+ * Folds the unified MCP tool registry (#615) — specifically the Operations
+ * profile (#617) — into the agent's toolset. The agent consumes the *same*
+ * registry the MCP HTTP server exposes, RBAC-filtered for its configured user,
+ * so operators get one tool surface with one permission model.
+ *
+ * Two-step, mirroring the registry's own security model:
+ *   1. `visibleTo(agentUser)` narrows *listing* — the LLM only sees tools it is
+ *      likely allowed to call. This is NOT a security boundary.
+ *   2. Real enforcement runs in the operation handler at call time: each call
+ *      dispatches through Harper's operations runtime with `hdb_user` set to the
+ *      agent's configured identity, so `verifyPerms` gates it regardless of what
+ *      the LLM was shown.
+ *
+ * The Application profile (#618) is intentionally out of scope here; it can fold
+ * in the same way once per-Resource tool generation is wired for the agent.
+ */
+import { type AuthedUser } from '../components/mcp/toolRegistry.ts';
+import type { AgentTool } from './types.ts';
+/**
+ * Populate the Operations profile on the main thread. Idempotent: guarded so a
+ * second call (e.g. an `agent.enabled` flip via `set_agent_config`) is a no-op
+ * rather than re-walking `OPERATION_FUNCTION_MAP` and re-logging. The registry's
+ * `addTool` is `Map.set`-backed, so this stays correct whether or not the
+ * operator also enabled the `mcp:` HTTP surface.
+ */
+export declare function ensureOperationsToolsRegistered(): void;
+/**
+ * Adapt every Operations-profile registry tool into the agent's {@link AgentTool}
+ * shape. Call {@link ensureOperationsToolsRegistered} first so the profile is
+ * populated.
+ *
+ * Two identities, deliberately split:
+ *   - `listingUser` filters `visibleTo` at compose time — which tools the LLM is
+ *     *shown*. Listing is not a security boundary, so a startup snapshot is fine.
+ *   - `resolveIdentity()` is called *per tool call* to set `hdb_user`, so the
+ *     operation is enforced against the agent user's *current* role. This is what
+ *     honors a role revocation/change without a restart — the enforcement identity
+ *     is never cached in the handler closure.
+ */
+export declare function composeRegistryTools(listingUser: AuthedUser, resolveIdentity: () => Promise<AuthedUser>): AgentTool[];
+/** Test-only: reset the one-time registration guard between specs. */
+export declare function _resetRegistryToolsForTests(): void;