@prohost/cli 0.1.2 → 0.2.1

package/dist/agent/contract.js

@@ -38,6 +38,16 @@ export function conversationMessagesPath(conversationId) {
 export function agentRunCompletePath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
 }
+/**
+ * Ceiling on how many context entries are kept from one payload.
+ *
+ * The server bounds these, but the prompt is written to a child process's
+ * stdin and the harness is the last thing standing between a pathological
+ * payload and an agent's context window. Entries past the limit are dropped
+ * from the *front*, because both lists are oldest-first and the recent end is
+ * the part worth spending prompt on.
+ */
+export const MAX_CONTEXT_ENTRIES = 50;
 /**
  * Fallback for a server that predates `reply_instructions.body_field`.
  *
@@ -60,6 +70,60 @@ function obj(value) {
         ? value
         : {};
 }
+/**
+ * Keep the last {@link MAX_CONTEXT_ENTRIES} entries of a list the server sent.
+ *
+ * Everything about this is deliberately forgiving. The two context lists are
+ * additive fields on an event this CLI already had to parse without them, and
+ * they will keep changing shape after this build is published: a version that
+ * throws — or that drops the whole run — because a list arrived as `null`, held
+ * an entry with a new key, or carried one malformed row would turn a server-side
+ * improvement into a fleet-wide outage of laptops nobody can redeploy. A
+ * missing, null, or wrong-typed list degrades to "this server doesn't send it",
+ * and one bad entry costs that entry only.
+ */
+function contextList(value, parseEntry) {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const parsed = parseEntry(raw);
+        if (parsed !== null)
+            entries.push(parsed);
+    }
+    if (entries.length === 0)
+        return undefined;
+    return entries.slice(-MAX_CONTEXT_ENTRIES);
+}
+/**
+ * Validate ``reply_instructions.body_extra``.
+ *
+ * Anything that isn't a plain object is treated as absent rather than as an
+ * error: these fields are additive, and a malformed one must not cost the run
+ * its reply. Values are passed through untouched — the server owns their
+ * meaning, and coercing them here would be this CLI inventing a schema it does
+ * not have.
+ */
+function bodyExtra(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = value;
+    return Object.keys(entries).length > 0 ? entries : undefined;
+}
+function parseMessage(entry) {
+    const text = str(entry.text);
+    if (!text)
+        return null;
+    return { text, author: str(entry.author), role: str(entry.role), at: str(entry.at) };
+}
+function parseMemory(entry) {
+    const content = str(entry.content);
+    if (!content)
+        return null;
+    return { content, scope: str(entry.scope) };
+}
 /**
  * Extract the event body from a websocket frame's payload.
  *
@@ -87,6 +151,7 @@ export function parseRunRequest(data) {
     const trigger = obj(data.trigger);
     const replyInstructions = obj(data.reply_instructions);
     const completion = obj(data.completion);
+    const context = obj(data.context);
     const declaredSurface = str(replyInstructions.surface);
     const conversationId = str(data.conversation_id) ?? str(replyInstructions.conversation_id);
     const taskId = str(data.task_id) ?? str(replyInstructions.task_id);
@@ -120,6 +185,12 @@ export function parseRunRequest(data) {
         // without a CLI release. A path with no nameable field is not postable;
         // keep the known-surface fallback only for old events.
         reply_body_key: str(replyInstructions.body_field) ?? legacyBodyKeyFor(surface),
+        reply_body_extra: bodyExtra(replyInstructions.body_extra),
         completion_path: str(completion.path) ?? agentRunCompletePath(runId),
+        // Accepted both at the top level and nested under `context`, because the
+        // server can move them without a CLI release either way — and a published
+        // CLI cannot be redeployed to follow.
+        recent_messages: contextList(data.recent_messages ?? context.recent_messages, parseMessage),
+        memories: contextList(data.memories ?? context.memories, parseMemory),
     };
 }

package/dist/agent/credentials.d.ts

@@ -68,6 +68,21 @@ export declare function streamUrlFor(credentials: AgentCredentials, fallback: st
 export declare function prohostHome(env?: NodeJS.ProcessEnv): string;
 /** Absolute path of the credential file. */
 export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Default working directory for the agent command.
+ *
+ * A dedicated, boring directory — **not** whatever the operator happened to
+ * `cd` into. Coding agents read their working directory as configuration: a
+ * `CLAUDE.md`, a `.claude/settings.json` permission list, a project `.mcp.json`.
+ * Launched from a checkout of some unrelated service, the agent inherits that
+ * repo's instructions and denials and answers a customer's question as if it
+ * were working on that codebase — which is exactly what happened when this was
+ * first run in production from a dev checkout. Defaulting somewhere neutral
+ * makes the inherited-context case something you opt into with `--workdir`.
+ */
+export declare function workspacePath(env?: NodeJS.ProcessEnv): string;
+/** Create the workspace directory if it isn't there, and return its path. */
+export declare function ensureWorkspace(env?: NodeJS.ProcessEnv): string;
 /**
  * Show enough of a secret to identify it and no more — ``ph_live_ab…`` style.
  * Anything shorter than the prefix is reported as ``***`` so a short or

package/dist/agent/credentials.js

@@ -71,6 +71,27 @@ export function prohostHome(env = process.env) {
 export function credentialsPath(env = process.env) {
     return path.join(prohostHome(env), 'agent.json');
 }
+/**
+ * Default working directory for the agent command.
+ *
+ * A dedicated, boring directory — **not** whatever the operator happened to
+ * `cd` into. Coding agents read their working directory as configuration: a
+ * `CLAUDE.md`, a `.claude/settings.json` permission list, a project `.mcp.json`.
+ * Launched from a checkout of some unrelated service, the agent inherits that
+ * repo's instructions and denials and answers a customer's question as if it
+ * were working on that codebase — which is exactly what happened when this was
+ * first run in production from a dev checkout. Defaulting somewhere neutral
+ * makes the inherited-context case something you opt into with `--workdir`.
+ */
+export function workspacePath(env = process.env) {
+    return path.join(prohostHome(env), 'workspace');
+}
+/** Create the workspace directory if it isn't there, and return its path. */
+export function ensureWorkspace(env = process.env) {
+    const dir = workspacePath(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
 /**
  * Show enough of a secret to identify it and no more — ``ph_live_ab…`` style.
  * Anything shorter than the prefix is reported as ``***`` so a short or

package/dist/agent/daemon.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Keeping `agent run` alive across logouts, crashes, and reboots.
+ *
+ * A paired agent that only runs while a terminal window is open is not a
+ * teammate — it is a demo. Someone @-mentions it at 2am, the laptop had
+ * rebooted for an update, and the run times out server-side with no indication
+ * that anything is wrong on this end. So the harness ships a way to hand itself
+ * to the OS supervisor.
+ *
+ * On macOS that is a per-user launchd agent: a plist in `~/Library/LaunchAgents`
+ * with `KeepAlive`, bootstrapped into the `gui/$UID` domain so it starts at
+ * login and is restarted whenever it exits. On Linux there is no equivalent
+ * this CLI can write safely (systemd-user layouts differ per distro and per
+ * init), so we print a unit file to install by hand rather than guess.
+ *
+ * Only plist *generation* is unit-tested. Asserting on `launchctl` would be
+ * testing Apple's binary, and doing it for real in CI would install a live
+ * daemon on the runner.
+ */
+/** Reverse-DNS prefix every generated label starts with. */
+export declare const LAUNCHD_LABEL_PREFIX = "ai.prohost.agent";
+export interface DaemonSpec {
+    /** launchd label, also the plist filename stem. */
+    label: string;
+    /** argv[0] plus arguments, exactly as launchd will exec them. */
+    programArguments: string[];
+    /** Working directory for the harness process. */
+    workdir: string;
+    /** Combined stdout/stderr destination. */
+    logPath: string;
+    /** Extra environment launchd must set — launchd inherits almost nothing. */
+    env?: Record<string, string>;
+}
+/**
+ * Label for the daemon serving one `$PROHOST_HOME`.
+ *
+ * Keyed on the home directory rather than on the agent id, because the home
+ * directory is what actually scopes an install: there is exactly one
+ * `agent.json` in it, so every daemon pointed at the same home runs the *same*
+ * agent no matter which agent was paired when it was installed. An agent-keyed
+ * label got that backwards — re-pairing and re-installing produced a second
+ * label whose plist loaded the same single credential, so both jobs came up as
+ * the new agent (two harnesses, duplicate work) and `uninstall-daemon` could no
+ * longer name the first one to remove it.
+ *
+ * Running two agents at once is still supported, and this is what makes it
+ * honest: give each one its own `$PROHOST_HOME`, and they get separate
+ * credentials, separate ledgers, and separate daemons.
+ *
+ * A digest rather than the path itself — a label is a filename, and home
+ * directories contain spaces, `~`, and non-ASCII.
+ */
+export declare function launchdLabel(home: string): string;
+/** Where a label's plist lives. */
+export declare function launchdPlistPath(label: string, home?: string): string;
+/**
+ * Render the launchd property list for a daemon spec.
+ *
+ * `KeepAlive` is unconditional `true` rather than `SuccessfulExit: false`:
+ * `agent run` exits 0 on a clean shutdown *and* on a fatal auth error, and a
+ * daemon that stops restarting after a revoked-then-restored credential is
+ * exactly the silent-agent failure this whole feature exists to prevent.
+ * Restarting into a rejected credential is loud and cheap; not restarting is
+ * quiet and expensive.
+ */
+export declare function buildLaunchdPlist(spec: DaemonSpec): string;
+/**
+ * The systemd-user unit we print on Linux.
+ *
+ * Printed rather than installed. `systemctl --user` needs a running user
+ * manager and lingering enabled for it to survive logout, neither of which this
+ * CLI can arrange without making decisions about the machine that aren't its
+ * to make.
+ */
+export declare function buildSystemdUnit(spec: DaemonSpec): string;
+/** Reconstruct the `agent run` argv a daemon should launch. */
+export interface HarnessInvocation {
+    /** Interpreter to exec — normally the Node binary running this process. */
+    execPath: string;
+    /** Absolute path of the CLI entrypoint script. */
+    scriptPath: string;
+    /** The `--exec` command, verbatim. */
+    exec: string;
+    workdir: string;
+    timeoutSeconds?: number;
+    machine?: string;
+    url?: string;
+    allowUnverified?: boolean;
+    /** Gate tools behind permission prompts (the `--safe-tools` opt-out). */
+    safeTools?: boolean;
+}
+export declare function harnessArguments(invocation: HarnessInvocation): string[];
+/** Default log destination — alongside the credential and the run ledger. */
+export declare function agentLogPath(env?: NodeJS.ProcessEnv): string;
+export interface InstallResult {
+    ok: boolean;
+    /** Human-readable report, already formatted for the terminal. */
+    message: string;
+    /** Path written, when one was. */
+    plistPath?: string;
+}
+type Runner = (command: string, args: string[]) => {
+    status: number | null;
+    stderr: string;
+};
+/**
+ * Write the plist and hand it to launchd.
+ *
+ * `bootout` first, ignoring its result: bootstrapping a label that is already
+ * loaded fails outright, so a plain re-install of an agent whose `--exec`
+ * changed would otherwise keep running the old command and report success.
+ */
+export declare function installLaunchdDaemon(spec: DaemonSpec, options?: {
+    home?: string;
+    uid?: number;
+    run?: Runner;
+}): InstallResult;
+/**
+ * Unload the daemon and delete its plist. Missing pieces are not an error.
+ *
+ * Reports whether anything was actually there. "✓ Removed" printed over an
+ * empty home reads as confirmation that a daemon has been stopped — which is
+ * exactly the wrong thing to tell someone whose agent is still running from a
+ * *different* `$PROHOST_HOME` than the one they just pointed this at.
+ */
+export declare function uninstallLaunchdDaemon(label: string, options?: {
+    home?: string;
+    uid?: number;
+    run?: Runner;
+}): InstallResult;
+export {};

package/dist/agent/daemon.js

@@ -0,0 +1,274 @@
+/**
+ * Keeping `agent run` alive across logouts, crashes, and reboots.
+ *
+ * A paired agent that only runs while a terminal window is open is not a
+ * teammate — it is a demo. Someone @-mentions it at 2am, the laptop had
+ * rebooted for an update, and the run times out server-side with no indication
+ * that anything is wrong on this end. So the harness ships a way to hand itself
+ * to the OS supervisor.
+ *
+ * On macOS that is a per-user launchd agent: a plist in `~/Library/LaunchAgents`
+ * with `KeepAlive`, bootstrapped into the `gui/$UID` domain so it starts at
+ * login and is restarted whenever it exits. On Linux there is no equivalent
+ * this CLI can write safely (systemd-user layouts differ per distro and per
+ * init), so we print a unit file to install by hand rather than guess.
+ *
+ * Only plist *generation* is unit-tested. Asserting on `launchctl` would be
+ * testing Apple's binary, and doing it for real in CI would install a live
+ * daemon on the runner.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { prohostHome } from './credentials.js';
+/** Reverse-DNS prefix every generated label starts with. */
+export const LAUNCHD_LABEL_PREFIX = 'ai.prohost.agent';
+/** Hex characters of the home-directory digest that go into the label. */
+const LABEL_DIGEST_CHARS = 8;
+/**
+ * Label for the daemon serving one `$PROHOST_HOME`.
+ *
+ * Keyed on the home directory rather than on the agent id, because the home
+ * directory is what actually scopes an install: there is exactly one
+ * `agent.json` in it, so every daemon pointed at the same home runs the *same*
+ * agent no matter which agent was paired when it was installed. An agent-keyed
+ * label got that backwards — re-pairing and re-installing produced a second
+ * label whose plist loaded the same single credential, so both jobs came up as
+ * the new agent (two harnesses, duplicate work) and `uninstall-daemon` could no
+ * longer name the first one to remove it.
+ *
+ * Running two agents at once is still supported, and this is what makes it
+ * honest: give each one its own `$PROHOST_HOME`, and they get separate
+ * credentials, separate ledgers, and separate daemons.
+ *
+ * A digest rather than the path itself — a label is a filename, and home
+ * directories contain spaces, `~`, and non-ASCII.
+ */
+export function launchdLabel(home) {
+    const digest = createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, LABEL_DIGEST_CHARS);
+    return `${LAUNCHD_LABEL_PREFIX}.${digest}`;
+}
+/** Where a label's plist lives. */
+export function launchdPlistPath(label, home = os.homedir()) {
+    return path.join(home, 'Library', 'LaunchAgents', `${label}.plist`);
+}
+/**
+ * XML-escape a plist string value.
+ *
+ * Not optional politeness: an `--exec` command is arbitrary shell the operator
+ * typed, and `--exec 'sh -c "foo && bar"'` is a perfectly ordinary thing to
+ * want. Interpolated raw, its `&` alone produces a plist that `launchctl`
+ * rejects as malformed — with an error that points at the file, not at the
+ * flag that poisoned it.
+ */
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function stringEntries(values, indent) {
+    return Object.entries(values).flatMap(([key, value]) => [
+        `${indent}<key>${xmlEscape(key)}</key>`,
+        `${indent}<string>${xmlEscape(value)}</string>`,
+    ]);
+}
+/**
+ * Render the launchd property list for a daemon spec.
+ *
+ * `KeepAlive` is unconditional `true` rather than `SuccessfulExit: false`:
+ * `agent run` exits 0 on a clean shutdown *and* on a fatal auth error, and a
+ * daemon that stops restarting after a revoked-then-restored credential is
+ * exactly the silent-agent failure this whole feature exists to prevent.
+ * Restarting into a rejected credential is loud and cheap; not restarting is
+ * quiet and expensive.
+ */
+export function buildLaunchdPlist(spec) {
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ' +
+            '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>',
+        `  <string>${xmlEscape(spec.label)}</string>`,
+        '  <key>ProgramArguments</key>',
+        '  <array>',
+        ...spec.programArguments.map((arg) => `    <string>${xmlEscape(arg)}</string>`),
+        '  </array>',
+        '  <key>WorkingDirectory</key>',
+        `  <string>${xmlEscape(spec.workdir)}</string>`,
+        '  <key>RunAtLoad</key>',
+        '  <true/>',
+        '  <key>KeepAlive</key>',
+        '  <true/>',
+        // Without this a crash-looping harness would be restarted as fast as it can
+        // fail, which on a bad credential means hammering the pairing endpoint.
+        '  <key>ThrottleInterval</key>',
+        '  <integer>10</integer>',
+        '  <key>StandardOutPath</key>',
+        `  <string>${xmlEscape(spec.logPath)}</string>`,
+        '  <key>StandardErrorPath</key>',
+        `  <string>${xmlEscape(spec.logPath)}</string>`,
+    ];
+    if (spec.env && Object.keys(spec.env).length > 0) {
+        lines.push('  <key>EnvironmentVariables</key>', '  <dict>', ...stringEntries(spec.env, '    '), '  </dict>');
+    }
+    lines.push('</dict>', '</plist>');
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Quote one `ExecStart` word for systemd.
+ *
+ * systemd re-splits `ExecStart` on whitespace, so joining argv with spaces
+ * silently corrupts any argument that contains one — and the very first thing
+ * this CLI passes is `--exec 'claude -p'`. Unquoted, systemd hands `--exec` the
+ * value `claude` and treats `-p` as a flag of its own; `codex exec -` loses two
+ * words the same way. Quoting is not decoration here, it is the difference
+ * between a working unit and one that starts the wrong process.
+ */
+function systemdQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * The systemd-user unit we print on Linux.
+ *
+ * Printed rather than installed. `systemctl --user` needs a running user
+ * manager and lingering enabled for it to survive logout, neither of which this
+ * CLI can arrange without making decisions about the machine that aren't its
+ * to make.
+ */
+export function buildSystemdUnit(spec) {
+    const environment = Object.entries(spec.env ?? {})
+        .map(([key, value]) => `Environment=${key}=${systemdQuote(value)}`)
+        .join('\n');
+    return [
+        '[Unit]',
+        'Description=ProhostAI paired agent',
+        'After=network-online.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `WorkingDirectory=${systemdQuote(spec.workdir)}`,
+        `ExecStart=${spec.programArguments.map(systemdQuote).join(' ')}`,
+        'Restart=always',
+        'RestartSec=10',
+        ...(environment ? [environment] : []),
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n');
+}
+export function harnessArguments(invocation) {
+    const args = [
+        invocation.execPath,
+        invocation.scriptPath,
+        'agent',
+        'run',
+        '--exec',
+        invocation.exec,
+        '--workdir',
+        invocation.workdir,
+    ];
+    if (invocation.timeoutSeconds !== undefined)
+        args.push('--timeout', String(invocation.timeoutSeconds));
+    if (invocation.machine)
+        args.push('--machine', invocation.machine);
+    if (invocation.url)
+        args.push('--url', invocation.url);
+    if (invocation.allowUnverified)
+        args.push('--allow-unverified');
+    if (invocation.safeTools)
+        args.push('--safe-tools');
+    return args;
+}
+/** Default log destination — alongside the credential and the run ledger. */
+export function agentLogPath(env = process.env) {
+    return path.join(prohostHome(env), 'agent.log');
+}
+const defaultRunner = (command, args) => {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    return { status: result.status, stderr: result.stderr ?? '' };
+};
+/**
+ * Write the plist and hand it to launchd.
+ *
+ * `bootout` first, ignoring its result: bootstrapping a label that is already
+ * loaded fails outright, so a plain re-install of an agent whose `--exec`
+ * changed would otherwise keep running the old command and report success.
+ */
+export function installLaunchdDaemon(spec, options = {}) {
+    const home = options.home ?? os.homedir();
+    const uid = options.uid ?? process.getuid?.() ?? 0;
+    const run = options.run ?? defaultRunner;
+    const plistPath = launchdPlistPath(spec.label, home);
+    const domain = `gui/${uid}`;
+    mkdirSync(path.dirname(plistPath), { recursive: true });
+    // 0600 rather than the usual 0644 for a LaunchAgent: this plist carries the
+    // installing shell's environment, and while today that is only PATH and
+    // PROHOST_HOME, a file whose whole job is "environment for a credentialed
+    // process" should not be readable by other local accounts. launchd runs it as
+    // the owning user, so nothing needs wider access.
+    writeFileSync(plistPath, buildLaunchdPlist(spec), { mode: 0o600 });
+    chmodSync(plistPath, 0o600);
+    run('launchctl', ['bootout', `${domain}/${spec.label}`]);
+    const bootstrap = run('launchctl', ['bootstrap', domain, plistPath]);
+    if (bootstrap.status !== 0) {
+        return {
+            ok: false,
+            plistPath,
+            message: `Wrote ${plistPath}, but \`launchctl bootstrap ${domain}\` failed` +
+                `${bootstrap.stderr.trim() ? `: ${bootstrap.stderr.trim()}` : '.'}\n` +
+                `Load it by hand with: launchctl bootstrap ${domain} ${plistPath}`,
+        };
+    }
+    run('launchctl', ['enable', `${domain}/${spec.label}`]);
+    return {
+        ok: true,
+        plistPath,
+        message: `✓ Installed ${spec.label}\n` +
+            `  plist: ${plistPath}\n` +
+            `  logs:  ${spec.logPath}\n` +
+            `  The agent now starts at login and is restarted if it exits.\n` +
+            // Said at install time because the alternative is finding out from a
+            // crash-loop in a log nobody is watching: a supervised process does not
+            // inherit the shell you installed from, so an --exec that depends on an
+            // exported API key works interactively and fails here.
+            `  It runs with only PATH and PROHOST_HOME from this shell. If your\n` +
+            `  command needs other environment (an API key, a proxy setting), point\n` +
+            `  --exec at a wrapper script that sets it.\n` +
+            `  Stop it with: prohost agent uninstall-daemon`,
+    };
+}
+/**
+ * Unload the daemon and delete its plist. Missing pieces are not an error.
+ *
+ * Reports whether anything was actually there. "✓ Removed" printed over an
+ * empty home reads as confirmation that a daemon has been stopped — which is
+ * exactly the wrong thing to tell someone whose agent is still running from a
+ * *different* `$PROHOST_HOME` than the one they just pointed this at.
+ */
+export function uninstallLaunchdDaemon(label, options = {}) {
+    const home = options.home ?? os.homedir();
+    const uid = options.uid ?? process.getuid?.() ?? 0;
+    const run = options.run ?? defaultRunner;
+    const plistPath = launchdPlistPath(label, home);
+    const existed = existsSync(plistPath);
+    run('launchctl', ['bootout', `gui/${uid}/${label}`]);
+    rmSync(plistPath, { force: true });
+    return {
+        ok: true,
+        plistPath,
+        message: existed
+            ? `✓ Removed ${label} (${plistPath})`
+            : `No daemon was installed for this PROHOST_HOME (looked for ${plistPath}).\n` +
+                `  Nothing to remove. If an agent is still running, it belongs to a\n` +
+                `  different PROHOST_HOME — check with: launchctl list | grep ${LAUNCHD_LABEL_PREFIX}`,
+    };
+}

package/dist/agent/prompt.d.ts

@@ -10,8 +10,23 @@ import type { AgentRunRequest } from './contract.js';
 export interface PromptContext {
     /** Display name of the paired AI employee, e.g. "Ada". */
     agentName: string;
-    /** MCP endpoint the agent can use to act back into the account. */
-    mcpUrl?: string;
+    /**
+     * MCP server name the run's tools are registered under, e.g. `prohost`.
+     *
+     * Set **only** when the harness actually wired those tools into this
+     * invocation. Naming tools the child cannot call is worse than naming
+     * nothing: the agent reports having looked something up when it did not.
+     */
+    mcpServerName?: string;
+    /**
+     * Tools are behind permission prompts this run (`--safe-tools`).
+     *
+     * Changes what is true, so it has to change what the prompt says. Gated, a
+     * tool needing approval will never run and the agent must plan around that.
+     * Ungated — the default — it can act, and telling it otherwise would make it
+     * decline work it is perfectly able to do.
+     */
+    toolsGated?: boolean;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;

package/dist/agent/prompt.js

@@ -6,6 +6,24 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+/**
+ * Render one line of thread history.
+ *
+ * The role is a parenthetical *qualifier* on a name, not a substitute for one:
+ * a row with a role and no author — which is what a system row like
+ * `{role: "event", text: "Reservation confirmed"}` looks like — reads as
+ * `event: …` rather than the nonsense `someone (event): …`.
+ */
+function renderMessage(message) {
+    const who = message.author ?? message.role ?? 'someone';
+    const role = message.author && message.role ? ` (${message.role})` : '';
+    const when = message.at ? `[${message.at}] ` : '';
+    return `${when}${who}${role}: ${message.text}`;
+}
+/** Render one remembered fact. */
+function renderMemory(memory) {
+    return memory.scope ? `- (${memory.scope}) ${memory.content}` : `- ${memory.content}`;
+}
 /** Build the stdin prompt for one run. */
 export function buildPrompt(run, context) {
     const name = run.agent_name ?? context.agentName;
@@ -42,12 +60,18 @@ export function buildPrompt(run, context) {
     // only handle the agent has on what was actually said.
     if (run.trigger_message_id)
         facts.push(`Comment/message id: ${run.trigger_message_id}`);
-    if (context.mcpUrl) {
-        facts.push(`ProhostAI MCP endpoint (for looking things up): ${context.mcpUrl}`);
-    }
     if (facts.length > 0) {
         lines.push('Context:', ...facts.map((f) => `- ${f}`), '');
     }
+    // Memories first, then the thread, then the message that woke the agent:
+    // oldest and most general context at the top, the thing being answered last
+    // and closest to the instruction.
+    if (run.memories?.length) {
+        lines.push('Things you remember (from earlier work in this workspace):', ...run.memories.map(renderMemory), '');
+    }
+    if (run.recent_messages?.length) {
+        lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
+    }
     if (run.trigger_text) {
         // The server caps this excerpt, so say so rather than let an agent assume
         // it has the whole message.
@@ -56,6 +80,40 @@ export function buildPrompt(run, context) {
     else {
         lines.push('The message text was not included in the event.', '');
     }
+    // An agent that doesn't know it is headless narrates as if it were mid-
+    // session — "let me connect to that", "I'll check once the tools load" —
+    // and that text is what gets posted to a customer, describing a lookup that
+    // never happened. Saying the shape of the invocation out loud is the cheapest
+    // fix; the alternative is a reply that is confidently wrong about its own
+    // capabilities.
+    lines.push('How you are running:', '- This is a single non-interactive turn. Nobody is at a terminal, so', context.toolsGated
+        ? '  any tool that would need approval will not run — plan around that\n' +
+            '  rather than asking for permission, which gets no answer.'
+        : '  nothing will stop to ask you for permission: your tools run as soon\n' +
+            '  as you call them. Do the work rather than proposing it — but that\n' +
+            '  also means a mistaken action happens for real, so check before you\n' +
+            '  change or delete anything.', '- Nothing about your access changes after this turn. Do not say a tool is', '  "connecting", "loading", or about to become available, and do not', '  promise to follow up.', 
+    // Claude Code lazy-loads part of its catalog — WebSearch/WebFetch among
+    // them — so a run that inspects its loaded tools concludes it cannot
+    // browse and says so to a customer, when one ToolSearch call away it
+    // could. Field-observed on the first 0.2.0 deployment; phrased
+    // conditionally because other `--exec` brains have no ToolSearch.
+    '- If you have a ToolSearch tool, part of your toolkit is deferred and', '  invisible until loaded — web browsing (WebSearch, WebFetch) usually', '  is. Search ToolSearch for a capability before telling anyone you', '  lack it.', "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
+    // Deliberately does not list which domains are reachable. A paired
+    // credential holds a narrow, server-chosen scope set — the current default
+    // covers conversations, tasks, cleanings and approvals but NOT reservations
+    // or listings — and any list written here is a promise this CLI cannot
+    // keep across pairings or across changes to the default scopes. Naming
+    // domains the credential can't reach is the same failure as naming an MCP
+    // endpoint it can't call: the agent reports a lookup it never made.
+    context.mcpServerName
+        ? `- You have ProhostAI tools (mcp__${context.mcpServerName}__*). They are the sanctioned ` +
+            'way to look up workspace data, so use them rather than guessing. Your credential is ' +
+            'deliberately narrow and does not reach every part of the workspace: if a tool returns ' +
+            'a permission error, that is a real limit rather than a glitch — say what you could not ' +
+            'look up instead of retrying it or answering as if you had.'
+        : '- You have no ProhostAI tools in this run. Everything you know about this ' +
+            'workspace is what is written above.', '');
     // Postability is a separate question from what the run is about: a task run
     // has no comment route in the external API yet, so the agent must be told its
     // output won't be posted rather than left to assume it will.