@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/tool-identity.js

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ServiceError } from './protocol.js';
+export const sharedUserWarning = (user) => `Tool execution runs as ${user}, the same OS user that holds the provider credential. Set --tools-user to separate them.`;
+export function serviceToolIdentity() {
+    const user = userInfo().username;
+    return {
+        mode: 'service-user',
+        user,
+        uid: process.getuid?.() ?? -1,
+        prefix: [],
+        warning: sharedUserWarning(user),
+    };
+}
+const run = (argv, input) => spawnSync(argv[0], argv.slice(1), {
+    env: { PATH: '/usr/local/bin:/usr/bin:/bin', LANG: 'C' },
+    input,
+    encoding: 'utf8',
+    timeout: 10000,
+    killSignal: 'SIGKILL',
+    maxBuffer: 1 << 20,
+});
+/** Fail closed unless the tools user exists, is reachable without a password, and cannot read state. */
+export function probeToolsUser(user, stateDir, prefix = ['sudo', '-n', '-u', user, '--']) {
+    if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(user))
+        throw new Error('--tools-user must be a plain Unix user name');
+    if (process.platform !== 'linux' && prefix[0] === 'sudo')
+        throw new Error('--tools-user is supported on Linux hosts only');
+    const id = run([...prefix, '/usr/bin/id', '-u']);
+    const uid = Number(String(id.stdout).trim());
+    if (id.status !== 0 || !Number.isSafeInteger(uid))
+        throw new Error(`Cannot run as tools user ${user} (sudo -n -u ${user} failed); see docs/security.md host setup`);
+    if (uid === 0 || uid === process.getuid?.())
+        throw new Error('The tools user must be an unprivileged user distinct from the service user');
+    if (run([...prefix, '/usr/bin/test', '-r', stateDir]).status === 0)
+        throw new Error(`Tools user ${user} can read the Salaam state directory; restrict it to 0700`);
+    return { mode: 'tools-user', user, uid, prefix, warning: null };
+}
+export function toolArgv(identity, argv) {
+    return [...identity.prefix, ...argv];
+}
+/** Kill a tool process group owned by the tools user; the daemon cannot signal another uid. */
+export function killToolGroup(identity, pgid) {
+    if (identity.mode !== 'tools-user' || !Number.isSafeInteger(pgid) || pgid < 2)
+        return;
+    run(toolArgv(identity, ['/bin/kill', '-KILL', '--', '-' + pgid]));
+}
+const here = fileURLToPath(import.meta.url);
+/** Source runs (tests) use the built helper; packages ship it beside this file. */
+export const EDIT_HELPER = here.endsWith('.ts')
+    ? join(dirname(here), '..', 'dist/src/local-edit-helper.js')
+    : join(dirname(here), 'local-edit-helper.js');
+/** Apply reviewed edits as the tools user. Reports each applied path; any failure throws. */
+export function applyEditsAsTools(identity, root, edits, applied) {
+    if (!existsSync(EDIT_HELPER))
+        throw new ServiceError('tool_identity', 'Edit helper is missing');
+    const result = run(toolArgv(identity, [process.execPath, EDIT_HELPER, root]), JSON.stringify(edits));
+    for (const line of String(result.stdout ?? '').split('\n')) {
+        if (line.startsWith('applied '))
+            applied(JSON.parse(line.slice(8)));
+    }
+    if (result.status !== 0)
+        throw new ServiceError('tool_identity', `Edit as ${identity.user} failed: ${String(result.stderr ?? '')
+            .trim()
+            .slice(0, 400)}`);
+}

package/dist/src/tui-activity.js

@@ -0,0 +1,99 @@
+import { humanTool, safeText } from './tui-theme.js';
+const lineCount = (text) => (text === '' ? 0 : text.replace(/\n$/, '').split('\n').length);
+function short(text, max = 60) {
+    const first = safeText(text).split('\n')[0].trim();
+    return first.length > max ? first.slice(0, max - 1) + '…' : first;
+}
+/** The recorded result of a local command: its exit code and output, even from a truncated record. */
+function commandResult(output) {
+    if (!output)
+        return {};
+    try {
+        const parsed = JSON.parse(output);
+        return { exit: parsed.exit_code, text: parsed.output };
+    }
+    catch {
+        const exit = /"exit_code":(-?\d+|null)/.exec(output)?.[1];
+        return exit === undefined ? {} : { exit: exit === 'null' ? null : Number(exit) };
+    }
+}
+export function toolLine(tool, input, finished, tail = 3) {
+    const state = !finished ? 'running' : finished.failed ? 'failed' : 'finished';
+    let args = {};
+    try {
+        args = JSON.parse(input ?? '{}');
+    }
+    catch { }
+    if (tool === 'salaam_local' && args.action === 'edit' && Array.isArray(args.edits)) {
+        let added = 0, removed = 0, created = false;
+        for (const edit of args.edits) {
+            if (edit.replacements?.length)
+                for (const r of edit.replacements) {
+                    added += lineCount(r.new);
+                    removed += lineCount(r.old);
+                }
+            else if (typeof edit.content === 'string') {
+                added += lineCount(edit.content);
+                if (edit.sha256 === null)
+                    created = true;
+            }
+        }
+        const what = args.edits.length === 1
+            ? safeText(String(args.edits[0].path ?? ''))
+            : `${args.edits.length} files`;
+        return {
+            state,
+            label: `Edit ${what} +${added} −${removed}${created ? ' (new)' : ''}`,
+            tail: [],
+        };
+    }
+    if (tool === 'salaam_local' && args.action === 'command' && typeof args.command === 'string') {
+        const result = commandResult(finished?.output);
+        const ended = !finished || args.background
+            ? args.background && finished
+                ? ' · background'
+                : ''
+            : result.exit === 0
+                ? ' ✓ exit 0'
+                : result.exit === undefined || result.exit === null
+                    ? finished.failed
+                        ? ' × did not finish'
+                        : ''
+                    : ` × exit ${result.exit}`;
+        const lines = (result.text ?? '')
+            .replace(/\n+$/, '')
+            .split('\n')
+            .filter((l) => l.trim() !== '');
+        return {
+            state: finished && result.exit !== undefined && result.exit !== null && result.exit !== 0
+                ? 'failed'
+                : state,
+            label: `Bash ${short(args.command)}${ended}`,
+            tail: finished ? lines.slice(-tail).map((l) => short(l, 120)) : [],
+            ...(result.text !== undefined ? { full: result.text.replace(/\n+$/, '') } : {}),
+        };
+    }
+    return { state, label: humanTool(tool, input), tail: [] };
+}
+/** The verb the progress line shows for what the agent is doing now. */
+export function activityVerb(running) {
+    if (!running)
+        return 'Thinking';
+    if (running.label.startsWith('Edit '))
+        return 'Editing';
+    if (running.label.startsWith('Bash '))
+        return 'Running ' + running.label.slice(5);
+    return running.label;
+}
+const SPIN = ['◐', '◓', '◑', '◒'];
+/** The live progress line while a turn runs: spinner, verb, elapsed seconds, tokens, interrupt hint. */
+export function progressLine(verb, startedAt, now, tokens) {
+    const seconds = Math.max(0, Math.floor((now - startedAt) / 1000));
+    const elapsed = seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+    return [
+        SPIN[seconds % SPIN.length] + ' ' + safeText(verb) + '…',
+        elapsed,
+        ...(tokens ? [tokens + ' tokens'] : []),
+        'esc to interrupt',
+    ].join(' · ');
+}

package/dist/src/tui-classifier.js

@@ -0,0 +1,25 @@
+/** Picker rows: every configured reviewer, then Off. Empty when there is nothing to choose. */
+export function classifierItems(v) {
+    if (!v.configured || v.pinned)
+        return [];
+    const mark = (on) => (on ? '● ' : '○ ');
+    return [
+        ...v.options.map((o) => ({
+            value: o.name,
+            label: mark(v.choice === o.name) + o.name,
+            description: `${o.provider} · ${o.model}`,
+        })),
+        { value: 'off', label: mark(v.choice === 'off') + 'Off', description: 'Rules only' },
+    ];
+}
+export function classifierNotice(v) {
+    if (!v.configured && v.choice === 'off' && !v.pinned)
+        return 'No command reviewer is configured; set --danger-classifier-config on the service.';
+    const what = v.enabled
+        ? `Command reviewer ${v.choice} (${v.model}) is on for this session` +
+            ` (if it does not answer: ${v.on_unavailable === 'ask' ? 'ask' : 'rules only'})`
+        : 'Command reviewer is off for this session';
+    return (what +
+        (v.pinned ? ', pinned by this host' : '') +
+        '. It can only make a command ask, never let one run.');
+}

package/dist/src/tui-client.js

@@ -4,7 +4,18 @@ import { join } from 'node:path';
 import { Outbox, acquireControl, subscribe } from './attach.js';
 import { call } from './transport.js';
 import { ServiceError, } from './protocol.js';
+/** All input tokens, cached or not. `known_input` alone is only the uncached part. */
+export const usageInput = (u) => u.known_input + (u.known_cache_read ?? 0) + (u.known_cache_write ?? 0);
+/** Known and estimated costs come from different observations, so the spend is their sum. */
+export const usageCost = (u) => u.known_cost + u.estimated_cost;
 /** An operator client only: the service owns workers, authority and durable outcomes. */
+/** "AGENTS.md" or "AGENTS.md (2 files)": which instruction files guide this session. */
+export function instructionsLabel(summary) {
+    const names = [...new Set(summary.files.map((f) => f.path.split('/').at(-1)))].join(' + ');
+    return summary.files.length > 1 ? `${names} (${summary.files.length} files)` : names;
+}
+/** Longest a stale control lease is waited out (the service's lease TTL is 15 s). */
+const CONTROL_LAPSE_MS = 16000;
 export class OperatorClient extends EventEmitter {
     state;
     socket;
@@ -87,6 +98,64 @@ export class OperatorClient extends EventEmitter {
         this.report('Permissions updated. Progression is unchanged; already-running commands are not stopped by this setting.');
         await this.refresh();
     }
+    /** Desk-session approval rules (phase 2a). */
+    async approvalRules() {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`);
+    }
+    /** Turn a reviewed request into a rule: its exact command words or its exact edited paths. */
+    async ruleFromOperation(operation, scope) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`, {
+            ...this.actor(),
+            request_id: randomUUID(),
+            scope,
+            operation_id: operation,
+        });
+    }
+    async addRule(scope, rule) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`, {
+            ...this.actor(),
+            request_id: randomUUID(),
+            scope,
+            rule,
+        });
+        this.report('Rule added.');
+    }
+    async removeRule(id) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules/${id}/remove`, {
+            ...this.actor(),
+        });
+        this.report('Rule removed.');
+    }
+    /** Your hooks and this workspace's, with their trust state (Phase 4b). */
+    async hooks() {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks`);
+    }
+    /** Trust this workspace's hooks file as reviewed; `digest` binds the content you saw. */
+    async trustHooks(digest) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks/trust`, {
+            ...this.actor(),
+            digest,
+        });
+        this.report('Workspace hooks trusted. They run from the next tool call or prompt.');
+    }
+    async revokeHooks() {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks/revoke`, { ...this.actor() });
+        this.report('Workspace hooks no longer trusted; they will not run.');
+    }
     async steer(text) {
         if (!this.snapshot)
             throw new Error('Choose a session first.');
@@ -118,6 +187,66 @@ export class OperatorClient extends EventEmitter {
         await this.refresh();
         this.report('Reverted the reviewed local edit. Conversation history is preserved.');
     }
+    async checkpoints() {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return (await call(this.socket, `/v1/sessions/${this.snapshot.id}/checkpoints`)).checkpoints;
+    }
+    async rewindReview(attempt, mode) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return call(this.socket, `/v1/sessions/${this.snapshot.id}/rewind?attempt=${encodeURIComponent(attempt)}&mode=${mode}`);
+    }
+    /** Returns the rewound turn's instruction so it can be edited and sent again. */
+    async rewind(review) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        const id = this.snapshot.id;
+        const result = await call(this.socket, `/v1/sessions/${id}/rewind`, {
+            ...this.actor(),
+            request_id: randomUUID(),
+            attempt_id: review.attempt_id,
+            mode: review.mode,
+            review_digest: review.digest,
+        });
+        if (result.state !== 'completed')
+            throw new Error('Rewind outcome is uncertain; inspect files before continuing.');
+        if (result.session_id !== id)
+            await this.open(result.session_id);
+        else
+            await this.refresh();
+        this.report((review.mode === 'conversation'
+            ? 'Conversation'
+            : review.mode === 'files'
+                ? 'Files'
+                : 'Files and conversation') +
+            ` rewound to before turn ${review.turn}.` +
+            (result.session_id !== id ? ' The earlier conversation stays as its own session.' : ''));
+        return result.text;
+    }
+    async changeReview() {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return (await call(this.socket, `/v1/sessions/${this.snapshot.id}/review`)).review;
+    }
+    async changeHunks(review, path) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        const q = new URLSearchParams({ path, base: review.base, current: review.current });
+        return (await call(this.socket, `/v1/sessions/${this.snapshot.id}/review/hunks?${q}`)).hunks;
+    }
+    async changeAct(review, action, path, hunk) {
+        if (!this.snapshot)
+            throw new Error('Choose a session first.');
+        return (await call(this.socket, `/v1/sessions/${this.snapshot.id}/review`, {
+            ...this.actor(),
+            action,
+            path,
+            base: review.base,
+            current: review.current,
+            ...(hunk ? { hunk } : {}),
+        })).review;
+    }
     async fork() {
         if (!this.snapshot)
             throw new Error('Choose a session first.');
@@ -196,14 +325,14 @@ export class OperatorClient extends EventEmitter {
         this.snapshot = await call(this.socket, `/v1/sessions/${id}/snapshot`);
         if (!options.observe) {
             try {
-                this.lease = await acquireControl(this.socket, id, this.clientId, options.takeover);
+                this.lease = await this.acquireOrWait(id, options.takeover);
             }
             catch (error) {
                 if (!(error instanceof ServiceError) ||
-                    !['control_conflict', 'control_required'].includes(error.code))
+                    !['control_conflict', 'control_required', 'control_busy'].includes(error.code))
                     throw error;
                 this.notice =
-                    'Another client has control. You are observing; use Take control to take over.';
+                    'Another terminal is using this session and still renews its control. You are observing; press ctrl+k and choose Take control to take it over.';
             }
         }
         if (this.lease)
@@ -219,6 +348,27 @@ export class OperatorClient extends EventEmitter {
         this.watcher = this.watch(id, generation);
         this.changed();
     }
+    /** Acquire control. A lease left by a terminal that was killed lapses within its short TTL, so
+     * wait that out once instead of opening as an observer; a live terminal renews and keeps it. */
+    async acquireOrWait(id, takeover) {
+        try {
+            return await acquireControl(this.socket, id, this.clientId, takeover);
+        }
+        catch (error) {
+            if (takeover || !(error instanceof ServiceError) || error.code !== 'control_busy')
+                throw error;
+            const snapshot = await call(this.socket, `/v1/sessions/${id}/snapshot`);
+            const wait = snapshot.control.expires_at - Date.now();
+            if (wait <= 0 || wait > CONTROL_LAPSE_MS)
+                throw error;
+            this.notice = `Waiting ${Math.ceil(wait / 1000)} s for the previous terminal's control to lapse…`;
+            this.changed();
+            await new Promise((done) => setTimeout(done, wait + 250));
+            const lease = await acquireControl(this.socket, id, this.clientId);
+            this.notice = 'You have control: the previous terminal had stopped.';
+            return lease;
+        }
+    }
     actor() {
         if (!this.lease)
             throw new Error('Take control before sending an instruction.');
@@ -263,11 +413,11 @@ export class OperatorClient extends EventEmitter {
         await job;
         this.changed();
     }
-    async submit(text, continues) {
+    async submit(text, continues, confirmSensitive = false) {
         this.actor();
         if (!this.snapshot || !this.outbox)
             throw new Error('Open a session first.');
-        const record = this.outbox.enqueue(text, this.snapshot.revision, continues);
+        const record = this.outbox.enqueue(text, this.snapshot.revision, continues, confirmSensitive);
         this.notice = 'Instruction saved locally. Delivering…';
         this.changed();
         try {
@@ -281,6 +431,8 @@ export class OperatorClient extends EventEmitter {
                 'Delivery pending. The saved instruction will be retried: ' + error.message;
         }
         await this.refresh().catch(() => { });
+        // A failed worker cannot take the instruction: say so instead of "accepted".
+        this.notice = sessionFailure(this.snapshot) ?? this.notice;
         this.changed();
         return record.request_id;
     }
@@ -368,6 +520,20 @@ export class OperatorClient extends EventEmitter {
         this.notice = 'Reviewed context admitted. Tool permissions are unchanged.';
         await this.refresh();
     }
+    /** Switch this session's model or thinking level between turns; the conversation carries on. */
+    async switchRoute(route) {
+        if (!this.snapshot)
+            throw new Error('Open a session first.');
+        await call(this.socket, `/v1/sessions/${this.snapshot.id}/route`, {
+            ...this.actor(),
+            route: {
+                provider: route.provider === 'salaam-proof' ? 'offline' : route.provider,
+                ...(route.provider === 'salaam-proof' ? {} : { model: route.model }),
+                ...(route.reasoning === undefined ? {} : { reasoning: route.reasoning }),
+            },
+        });
+        await this.refresh();
+    }
     async decide(approval, decision) {
         if (!this.outbox)
             throw new Error('Open a session first.');
@@ -459,6 +625,12 @@ export class OperatorClient extends EventEmitter {
                 ]);
                 if (generation !== this.generation)
                     return;
+                const before = this.snapshot?.id === snapshot.id ? this.snapshot.project_instructions : null;
+                const after = snapshot.project_instructions;
+                if (before && after && after.revision > before.revision)
+                    this.notice = after.files.length
+                        ? 'Project instructions changed · reloaded ' + instructionsLabel(after)
+                        : 'Project instructions removed';
                 this.snapshot = snapshot;
                 this.health = health;
                 this.commands = commands ?? [];
@@ -497,6 +669,7 @@ export class OperatorClient extends EventEmitter {
                 if (event.seq <= cursor || generation !== this.generation)
                     return;
                 cursor = event.seq;
+                this.emit('durable', event);
                 if ([
                     'attempt.completed',
                     'attempt.failed',
@@ -567,3 +740,11 @@ export class OperatorClient extends EventEmitter {
         await this.leave();
     }
 }
+/** What went wrong when a session's worker has failed, for the status line and the Changes tab. */
+export function sessionFailure(s) {
+    if (!s)
+        return undefined;
+    if (s.state !== 'unhealthy' && !(s.state === 'exited' && s.error))
+        return undefined;
+    return `Session stopped: ${s.error ?? 'the worker is not healthy'}. Fix it, then /new or ctrl+n for a fresh session.`;
+}

package/dist/src/tui-commands.js

@@ -4,10 +4,11 @@ export const SLASH_COMMANDS = [
     command('help', 'Show commands and their execution type', ['commands'], '[command]'),
     command('exit', 'Detach; preserve the session and running work', ['quit', 'q']),
     command('keys', 'Show keyboard shortcuts', ['hotkeys']),
-    command('model', 'Choose provider and model for a new session', ['models'], '[provider/model]'),
-    command('provider', 'Choose a provider for a new session', [], '[provider]'),
-    command('thinking', 'Choose reasoning effort for a new session', [], '[level]'),
-    command('coding', 'New local coding session with reviewed edits and unsandboxed commands', [], '[workspace]'),
+    command('model', 'Switch this session’s provider and model', ['models'], '[provider/model]'),
+    command('provider', 'Switch this session’s provider', [], '[provider]'),
+    command('thinking', 'Switch this session’s reasoning effort', [], '[level]'),
+    command('coding', 'New local coding session with reviewed edits and commands', [], '[workspace]'),
+    command('init', 'Draft an AGENTS.md for this repository; the edit asks for approval'),
     command('new', 'Create a session in a workspace', [], '[workspace]'),
     command('sessions', 'Switch or resume a session', ['resume'], '[session-id]'),
     command('name', 'Set a durable session label', ['rename'], '<name>'),
@@ -16,9 +17,15 @@ export const SLASH_COMMANDS = [
     command('cancel', 'Cancel an instruction with explicit confirmation', ['stop']),
     command('queue', 'Save a durable next-turn instruction, or inspect the queue', [], '[text]'),
     command('steer', 'Send recorded guidance to an active local turn; uncertain delivery never replays', [], '<text>'),
-    command('diff', 'Review workspace changes'),
+    command('diff', 'Review workspace changes file by file'),
+    command('commit', 'Draft a commit of the current work; staging and the commit each ask (uses provider credits)', [], undefined, 'model'),
+    command('branch', 'Switch to a branch, creating it if needed', [], '<name>', 'model'),
+    command('pr', 'Push this branch and open a pull request; both always ask, except in YOLO', [], '[base]', 'model'),
     command('tools', 'Inspect available capabilities and recorded tool activity'),
     command('permissions', 'Configure local permissions independently of task progression'),
+    command('mode', 'Cycle review → accept edits → auto (shift+tab)'),
+    command('full-access', 'Turn full access on or off: commands run without the OS sandbox; dangerous ones still ask'),
+    command('yolo', 'Turn YOLO on (type yolo to confirm) or off: no sandbox and no approvals'),
     command('approvals', 'Review exact pending approval requests'),
     command('context', 'Inspect session context, facts and usage'),
     command('usage', 'Show recorded usage and unknown observations'),
@@ -27,6 +34,7 @@ export const SLASH_COMMANDS = [
     command('export', 'Export full durable conversation as Markdown; never overwrite', [], '[path]'),
     command('settings', 'Choose terminal appearance and model settings'),
     command('fork', 'Fork an idle local conversation; keep the same workspace'),
+    command('rewind', 'Rewind files, conversation or both to before an earlier turn', [], '[turn]'),
     command('undo', 'Review and revert the last completed local edit; retain conversation history', [], '[reconcile]'),
     command('plan', 'Ask the model for a plan (uses provider credits; not a permission mode)', [], '[request]', 'model'),
     command('review', 'Ask the model to review workspace changes (uses provider credits)', [], '[focus]', 'model'),
@@ -35,6 +43,9 @@ export const SLASH_COMMANDS = [
     command('agents', 'Inspect native/external worker profiles and child work'),
     command('progression', 'Choose manual or bounded task progression; permissions stay separate'),
     command('tasks', 'Open durable task actions'),
+    command('classifier', 'Pick the small-model command reviewer for this session, or turn it off', [], '[name|on|off]'),
+    command('hooks', 'Show your hooks and this workspace’s; trust or revoke the workspace file', [], '[trust|revoke]'),
+    command('jobs', 'Show background commands and their output, or stop one', ['bg'], '[stop <id>]'),
 ];
 export const SLASH_COMPLETIONS = SLASH_COMMANDS.flatMap((c) => [c.name, ...c.aliases].map((name) => ({ name, description: c.description })));
 /** Slash input is always local; malformed or unknown commands never become prompts. */
@@ -65,3 +76,10 @@ export function slashHelp(name) {
         .map((c) => `/${c.name}${c.arguments ? ' ' + c.arguments : ''} — ${c.description} [${c.kind}]${c.aliases.length ? '\n  Aliases: ' + c.aliases.map((a) => '/' + a).join(', ') : ''}`)
         .join('\n');
 }
+/** What /init asks the agent to do. The write goes through the session's normal edit approval. */
+export const INIT_INSTRUCTION = [
+    'Draft an AGENTS.md for this repository.',
+    'First read the tree and the files that define how it is built and tested (package manifests, build and CI configuration, README, existing contributor docs, any CLAUDE.md).',
+    'Then write AGENTS.md at the repository root: a short overview, the exact commands to build, test, lint and format, the code layout, and conventions a contributor must follow.',
+    'Keep it under 150 lines, state only what the files show, and if AGENTS.md already exists, propose improvements to it instead of replacing it.',
+].join(' ');

package/dist/src/tui-composer.js

@@ -0,0 +1,113 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const CTRL_C_WINDOW_MS = 2000;
+export function ctrlCAction(input) {
+    if (input.running)
+        return 'interrupt';
+    if (input.text !== '')
+        return 'clear';
+    if (input.armedAt !== undefined && input.now - input.armedAt <= CTRL_C_WINDOW_MS)
+        return 'exit';
+    return 'arm';
+}
+const SECRET_PATTERNS = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}/,
+    /\bsk-ant-[A-Za-z0-9_-]{8,}/,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./,
+    /\b(password|passwd|secret|token|api[_-]?key|authorization)\s*[:=]\s*\S{6,}/i,
+    /\bbearer\s+[A-Za-z0-9._~+/-]{16,}/i,
+    /[A-Za-z0-9+_-]{48,}={0,2}/,
+];
+/** True when the text looks like it carries a credential; such text is never written to history. */
+export function looksSecret(text) {
+    return SECRET_PATTERNS.some((p) => p.test(text));
+}
+export const HISTORY_LIMIT = 500;
+export const HISTORY_ENTRY_LIMIT = 8192;
+/** Where this user's composer history lives: $XDG_STATE_HOME/salaam/history.json, or nowhere when
+ * SALAAM_HISTORY=off (history then lasts only for this terminal). */
+export function historyPath(env = process.env) {
+    if (env.SALAAM_HISTORY === 'off')
+        return undefined;
+    const base = env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state');
+    return join(base, 'salaam', 'history.json');
+}
+/** Per-user composer history, newest last, bounded, and without secret-looking entries. */
+export class ComposerHistory {
+    path;
+    entries = [];
+    constructor(path) {
+        this.path = path;
+        try {
+            if (path && existsSync(path)) {
+                const raw = JSON.parse(readFileSync(path, 'utf8'));
+                if (Array.isArray(raw))
+                    this.entries = raw
+                        .filter((e) => typeof e === 'string')
+                        .filter((e) => keepable(e))
+                        .slice(-HISTORY_LIMIT);
+            }
+        }
+        catch {
+            this.entries = [];
+        }
+    }
+    /** Adds a sent message. Returns false when it was not kept (blank, too long, or secret-looking). */
+    add(text) {
+        if (!keepable(text))
+            return false;
+        this.entries = this.entries.filter((e) => e !== text);
+        this.entries.push(text);
+        if (this.entries.length > HISTORY_LIMIT)
+            this.entries = this.entries.slice(-HISTORY_LIMIT);
+        this.save();
+        return true;
+    }
+    save() {
+        if (!this.path)
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            const tmp = this.path + '.tmp';
+            writeFileSync(tmp, JSON.stringify(this.entries), { mode: 0o600 });
+            chmodSync(tmp, 0o600);
+            renameSync(tmp, this.path);
+        }
+        catch {
+            // History is a convenience; failing to save never blocks sending.
+        }
+    }
+}
+function keepable(text) {
+    return text.trim() !== '' && text.length <= HISTORY_ENTRY_LIMIT && !looksSecret(text);
+}
+/**
+ * Reverse-incremental search: the newest entry older than `before` (an index into `entries`,
+ * newest last) that contains the query, case-insensitively. Returns its index or -1.
+ */
+export function searchHistory(entries, query, before) {
+    const q = query.toLowerCase();
+    for (let i = Math.min(before, entries.length) - 1; i >= 0; i--)
+        if (entries[i].toLowerCase().includes(q))
+            return i;
+    return -1;
+}
+/** The status-line text while searching, matching readline's wording. */
+export function searchPrompt(query, match) {
+    const shown = match === undefined ? '' : match.replace(/\s+/g, ' ').slice(0, 120);
+    return match === undefined && query !== ''
+        ? `(failing reverse-i-search)\`${query}': · esc cancels`
+        : `(reverse-i-search)\`${query}': ${shown} · enter keeps · ctrl+r older · esc cancels`;
+}
+/**
+ * `!command` from the composer. The TUI never runs it itself: it becomes an instruction for the
+ * model to run exactly this command through salaam_local, so it takes the same approval path,
+ * session mode, sandbox and danger check as any model command. Returns undefined for other text.
+ */
+export { shellPassthrough } from './shell-passthrough.js';