@ours.network/fleet 0.13.2 → 0.14.0

package/dist/owner-channel/commands.d.ts

@@ -0,0 +1,79 @@
+import type { SessionEvent, SessionSnapshot } from '../session/types.js';
+/**
+ * Fleet-level effects a deterministic owner command may trigger. Production
+ * uses the detached CLI (`fleetCliOps`); tests inject fakes so no command can
+ * ever bounce a real service from the suite.
+ */
+export interface OwnerFleetOps {
+    /** `ours-fleet restart` (keep) or `ours-fleet force-restart` (fresh) of this role. */
+    restart(mode: 'keep' | 'fresh'): Promise<void>;
+    /** `ours-fleet ls` output. */
+    list(): Promise<string>;
+}
+/**
+ * The narrow capability surface a command executor sees. Everything here is
+ * already scoped to the one role whose channel received the message; commands
+ * cannot name another agent or another recipient.
+ */
+export interface OwnerCommandContext {
+    role: string;
+    /** Harness id of the role (e.g. 'claude-code', 'codex'); gates forwarding. */
+    harness: string;
+    version: string;
+    snapshot(): SessionSnapshot;
+    interrupt(): Promise<void>;
+    /**
+     * Deliver raw slash text to the agent harness. Only commands the bundled
+     * ACP adapter for `harness` verifiably executes locally may be forwarded
+     * (see HARNESS_LOCAL_COMMANDS); anything else would reach the model as an
+     * ordinary prompt. The channel sends the acceptance and outcome notices
+     * itself.
+     */
+    runHarnessCommand(command: string): Promise<void>;
+    restart(mode: 'keep' | 'fresh'): Promise<void>;
+    fleetList(): Promise<string>;
+    recentEvents(limit: number): SessionEvent[];
+    readWorklogTail(maxChars: number): Promise<string | undefined>;
+    reply(text: string): Promise<void>;
+}
+export interface OwnerCommand {
+    /** Primary name without the leading slash. */
+    name: string;
+    aliases?: string[];
+    /** Shown in help; defaults to `/<name>`. */
+    usage?: string;
+    /** One-line description shown in help. */
+    summary: string;
+    execute(ctx: OwnerCommandContext, args: string): Promise<void>;
+}
+/**
+ * Commands each harness's bundled ACP adapter verifiably executes locally,
+ * pinned by test/acp-adapter-commands.test.ts against the shipped adapter
+ * artifacts. claude-agent-acp routes slash commands into the Claude SDK,
+ * which runs its builtins (/clear, /compact, /model) without a model turn;
+ * codex-acp intercepts only /compact — /clear and /model are not builtins
+ * and would fall through into sendPrompt, i.e. reach the model as an
+ * ordinary prompt. Unlisted harnesses forward nothing.
+ */
+export declare const HARNESS_LOCAL_COMMANDS: Record<string, readonly string[]>;
+/**
+ * The single source of truth for the deterministic owner-channel command set:
+ * /help renders exactly this table, so adding an entry here is the whole
+ * registration step for a new command.
+ */
+export declare const ownerCommands: OwnerCommand[];
+/** Trimmed slash-prefixed text is a command attempt and is never forwarded. */
+export declare const isOwnerCommandText: (text: string) => boolean;
+export declare function ownerCommandHelp(error?: string): string;
+/**
+ * Execute one authenticated owner command. `text` must already be trimmed,
+ * slash-prefixed, and from an authorized owner CID — the channel enforces the
+ * authority boundary before dispatch ever sees the message.
+ */
+export declare function dispatchOwnerCommand(text: string, ctx: OwnerCommandContext): Promise<void>;
+/**
+ * Production fleet effects: the detached ours-fleet CLI. The restart child is
+ * detached and unreferenced because a successful restart kills this very
+ * process; the reply and the durable wire record must already be on disk.
+ */
+export declare function fleetCliOps(role: string, configPath?: string): OwnerFleetOps;

package/dist/owner-channel/commands.js

@@ -0,0 +1,183 @@
+import { execFile, spawn } from 'node:child_process';
+import { ownerNotices } from './notices.js';
+/** A malformed invocation; the dispatcher answers it with annotated help. */
+class OwnerCommandUsageError extends Error {
+}
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const REPLY_MAX_CHARS = 3_500;
+const strip = (value, max) => String(value).replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, max);
+/** Like `strip`, but keeps newlines so multi-line listings stay readable. */
+const stripMultiline = (value, max) => String(value).replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, ' ').slice(0, max);
+/**
+ * Commands each harness's bundled ACP adapter verifiably executes locally,
+ * pinned by test/acp-adapter-commands.test.ts against the shipped adapter
+ * artifacts. claude-agent-acp routes slash commands into the Claude SDK,
+ * which runs its builtins (/clear, /compact, /model) without a model turn;
+ * codex-acp intercepts only /compact — /clear and /model are not builtins
+ * and would fall through into sendPrompt, i.e. reach the model as an
+ * ordinary prompt. Unlisted harnesses forward nothing.
+ */
+export const HARNESS_LOCAL_COMMANDS = {
+    'claude-code': ['clear', 'compact', 'model'],
+    codex: ['compact'],
+};
+/**
+ * Forward raw slash text to the harness only when the bundled adapter for
+ * this role's harness verifiably executes it locally; otherwise answer with
+ * a truthful refusal so the text can never reach the model as a prompt.
+ */
+const forwardHarnessCommand = (ctx, raw) => {
+    const name = raw.slice(1).split(/\s+/, 1)[0];
+    if (!(HARNESS_LOCAL_COMMANDS[ctx.harness] ?? []).includes(name))
+        return ctx.reply(ownerNotices.commandUnsupported(`/${name}`, ctx.harness));
+    return ctx.runHarnessCommand(raw);
+};
+/** Keep the LAST characters — tails are more useful than heads for logs. */
+const tail = (value, max) => {
+    const points = Array.from(value);
+    return points.length <= max ? value : `…${points.slice(-max).join('')}`;
+};
+const noArgs = (usage, run) => async (ctx, args) => {
+    if (args)
+        throw new OwnerCommandUsageError(`${usage} takes no arguments`);
+    await run(ctx);
+};
+/**
+ * The single source of truth for the deterministic owner-channel command set:
+ * /help renders exactly this table, so adding an entry here is the whole
+ * registration step for a new command.
+ */
+export const ownerCommands = [
+    {
+        name: 'help', aliases: ['commands'],
+        summary: 'list all deterministic owner-channel commands (alias: /commands)',
+        execute: async (ctx) => ctx.reply(ownerCommandHelp()),
+    },
+    {
+        name: 'status', summary: "report the agent's session state",
+        execute: noArgs('/status', async (ctx) => ctx.reply(ownerNotices.status(ctx.role, ctx.snapshot()))),
+    },
+    {
+        name: 'interrupt', summary: "cancel the agent's active turn",
+        execute: noArgs('/interrupt', async (ctx) => {
+            try {
+                await ctx.interrupt();
+            }
+            catch {
+                return ctx.reply(ownerNotices.interruptFailed(ctx.role));
+            }
+            await ctx.reply(ownerNotices.interrupted(ctx.role));
+        }),
+    },
+    {
+        name: 'clear', summary: "clear the agent's session context",
+        execute: noArgs('/clear', ctx => forwardHarnessCommand(ctx, '/clear')),
+    },
+    {
+        name: 'compact', summary: "compact the agent's session context",
+        execute: noArgs('/compact', ctx => forwardHarnessCommand(ctx, '/compact')),
+    },
+    {
+        name: 'model', usage: '/model <model-id>',
+        summary: 'switch the model the agent runs on',
+        execute: async (ctx, args) => {
+            if (!args)
+                throw new OwnerCommandUsageError('usage: /model <model-id>');
+            if (!MODEL_ID.test(args))
+                throw new OwnerCommandUsageError('model id must be alphanumeric with . _ : - only');
+            await forwardHarnessCommand(ctx, `/model ${args}`);
+        },
+    },
+    {
+        name: 'restart', summary: 'restart the agent, resuming its context',
+        execute: noArgs('/restart', ctx => ctx.restart('keep')),
+    },
+    {
+        name: 'force-restart', summary: 'restart the agent FRESH (context wiped)',
+        execute: noArgs('/force-restart', ctx => ctx.restart('fresh')),
+    },
+    {
+        name: 'ls', summary: 'list running fleet sessions',
+        execute: noArgs('/ls', async (ctx) => ctx.reply(`📊 Fleet sessions:\n${tail(stripMultiline(await ctx.fleetList(), 10_000), REPLY_MAX_CHARS)}`)),
+    },
+    {
+        name: 'peek', summary: 'summarize recent session activity (event shapes only, no content)',
+        execute: noArgs('/peek', async (ctx) => {
+            const lines = ctx.recentEvents(20).map(event => ['·', event.kind,
+                ...(event.title !== undefined ? [strip(event.title, 80)] : []),
+                ...(event.status !== undefined ? [`(${strip(event.status, 40)})`] : []),
+                ...(event.stopReason !== undefined ? [`(${strip(event.stopReason, 40)})`] : []),
+            ].join(' '));
+            await ctx.reply(lines.length
+                ? tail(`📊 Recent activity for ${ctx.role}:\n${lines.join('\n')}`, REPLY_MAX_CHARS)
+                : `📊 No recent session activity recorded for ${ctx.role}.`);
+        }),
+    },
+    {
+        name: 'worklog', summary: "tail the agent's worklog",
+        execute: noArgs('/worklog', async (ctx) => {
+            const worklog = await ctx.readWorklogTail(REPLY_MAX_CHARS);
+            await ctx.reply(worklog
+                ? `📊 Worklog tail for ${ctx.role}:\n${worklog}`
+                : `ℹ️ No worklog found for ${ctx.role}.`);
+        }),
+    },
+    {
+        name: 'version', summary: 'report the fleet version',
+        execute: noArgs('/version', async (ctx) => ctx.reply(`ℹ️ ours-fleet ${ctx.version}`)),
+    },
+];
+/** Trimmed slash-prefixed text is a command attempt and is never forwarded. */
+export const isOwnerCommandText = (text) => text.trim().startsWith('/');
+export function ownerCommandHelp(error) {
+    const table = ownerCommands
+        .map(command => `${command.usage ?? `/${command.name}`} — ${command.summary}`)
+        .join('\n');
+    return `${error ? `⚠️ ${error}\n\n` : ''}🧭 Deterministic owner-channel commands `
+        + '(handled by fleet; never sent to the agent as a prompt):\n'
+        + `${table}\n`
+        + 'Messages without a leading "/" reach the agent unchanged. '
+        + 'Unknown or malformed commands return this help.';
+}
+/**
+ * Execute one authenticated owner command. `text` must already be trimmed,
+ * slash-prefixed, and from an authorized owner CID — the channel enforces the
+ * authority boundary before dispatch ever sees the message.
+ */
+export async function dispatchOwnerCommand(text, ctx) {
+    const trimmed = text.trim();
+    const token = trimmed.split(/\s+/, 1)[0];
+    const name = token.slice(1).toLowerCase();
+    const args = trimmed.slice(token.length).trim();
+    const command = ownerCommands.find(entry => entry.name === name || entry.aliases?.includes(name));
+    if (!command)
+        return ctx.reply(ownerCommandHelp(`unknown command ${strip(token, 60)}`));
+    try {
+        await command.execute(ctx, args);
+    }
+    catch (error) {
+        if (error instanceof OwnerCommandUsageError)
+            return ctx.reply(ownerCommandHelp(error.message));
+        // The failure notice carries no internal detail; the channel logs it.
+        await ctx.reply(ownerNotices.commandFailed(command.usage ?? `/${command.name}`));
+        throw error;
+    }
+}
+/**
+ * Production fleet effects: the detached ours-fleet CLI. The restart child is
+ * detached and unreferenced because a successful restart kills this very
+ * process; the reply and the durable wire record must already be on disk.
+ */
+export function fleetCliOps(role, configPath) {
+    const cli = (args) => [process.argv[1], ...args, ...(configPath ? ['-c', configPath] : [])];
+    return {
+        restart: mode => new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, cli([mode === 'fresh' ? 'force-restart' : 'restart', role]), { detached: true, stdio: 'ignore' });
+            child.once('error', reject);
+            child.once('spawn', () => { child.unref(); resolve(); });
+        }),
+        list: () => new Promise((resolve, reject) => {
+            execFile(process.execPath, [process.argv[1], 'ls'], { timeout: 15_000, maxBuffer: 256 * 1024 }, (error, stdout) => error ? reject(error) : resolve(String(stdout).trim()));
+        }),
+    };
+}

package/dist/owner-channel/notices.d.ts

@@ -9,12 +9,19 @@ export declare const ownerNotices: {
     status: (role: string, snapshot: SessionSnapshot) => string;
     interrupted: (role: string) => string;
     interruptFailed: (role: string) => string;
+    commandStarted: (command: string) => string;
+    commandOutcome: (command: string, outcome: TurnOutcome, output?: string) => string;
+    commandFailed: (command: string) => string;
+    commandUnsupported: (command: string, harness: string) => string;
+    restarting: (role: string, command: string, mode: "keep" | "fresh") => string;
     attachmentRejected: (reason: string) => string;
     attachmentFailed: () => string;
     deliveryFailed: (role: string) => string;
     progress: (elapsedMs: number, phase: OwnerProgressPhase, started: number, completed: number, activityUpdates?: number) => string;
     authoredUpdate: (phase: OwnerUpdatePhase, message: string) => string;
     taskReport: (phase: OwnerTaskPhase, message: string) => string;
+    relayQueued: () => string;
+    relayRefused: (reason: string) => string;
     completedWithoutText: () => string;
     terminal: (outcome: TurnOutcome) => "✅ Request completed." | "🛑 Request was cancelled before completion." | "⚠️ The agent declined this request." | "⚠️ Request failed before completion." | "⚠️ Request ended without a confirmed completion.";
     chunk: (part: number, total: number) => string;

package/dist/owner-channel/notices.js

@@ -22,6 +22,23 @@ export const ownerNotices = {
     status: (role, snapshot) => `📊 ${role} status: ${snapshot.readiness}; session is ${snapshot.alive ? 'online' : 'offline'}.`,
     interrupted: (role) => `🛑 Interrupt sent to ${role}'s active turn.`,
     interruptFailed: (role) => `⚠️ Could not interrupt ${role}'s active turn.`,
+    commandStarted: (command) => `⏳ Running ${command} — the result will follow in this channel.`,
+    commandOutcome: (command, outcome, output) => {
+        switch (outcome) {
+            case 'completed': return `✅ ${command} completed.${output ? `\n${output}` : ''}`;
+            case 'cancelled': return `🛑 ${command} was cancelled before completion.`;
+            case 'refused': return `⚠️ ${command} was declined by the agent harness.`;
+            case 'failed': return `⚠️ ${command} failed before completion.`;
+            case 'inconclusive': return `⚠️ ${command} ended without a confirmed completion.`;
+        }
+    },
+    commandFailed: (command) => `⚠️ ${command} could not be executed.`,
+    commandUnsupported: (command, harness) => `⚠️ ${command} is not supported on the '${harness}' harness: its bundled ACP `
+        + 'adapter does not execute it locally, so forwarding it would deliver the '
+        + 'text to the model as an ordinary prompt. Nothing was forwarded.',
+    restarting: (role, command, mode) => `ℹ️ ${command} accepted — restarting ${role} ${mode === 'fresh'
+        ? 'FRESH (context wiped)' : '(context resumes)'}. `
+        + 'The channel goes quiet during the restart and resumes when the agent is back.',
     attachmentRejected: (reason) => `⚠️ Attachment rejected: ${reason}.`,
     attachmentFailed: () => '⚠️ Could not securely retrieve or admit this attachment request.',
     deliveryFailed: (role) => `⚠️ Could not deliver this request to ${role}.`,
@@ -52,6 +69,9 @@ export const ownerNotices = {
             case 'blocked': return `🚧 Follow-up blocked: ${message}`;
         }
     },
+    relayQueued: () => 'ℹ️ No owner has contacted this channel yet, so this message cannot be routed. '
+        + 'It stays queued and will be relayed after the first owner message arrives.',
+    relayRefused: (reason) => `⚠️ This message was not relayed to an owner: ${reason}.`,
     completedWithoutText: () => '✅ Request completed, but the agent returned no text.',
     terminal: (outcome) => {
         switch (outcome) {

package/dist/owner-channel/state.d.ts

@@ -1,3 +1,6 @@
+/** A send whose (dedupe-scoped) digest was already recorded: it must not repeat. */
+export declare class DuplicateSendError extends Error {
+}
 /** Durable bounded dedupe containing wire IDs only — never message or reply plaintext. */
 export declare class OwnerChannelState {
     private readonly path;
@@ -8,6 +11,44 @@ export declare class OwnerChannelState {
     has(wireId: string): boolean;
     remember(wireId: string): void;
 }
+export type OwnerConversationRouteBasis = 'last-inbound' | 'sole-owner';
+interface OwnerProactiveSend {
+    id: string;
+    contact: string;
+    digest: string;
+    at: number;
+    status: 'sending' | 'delivered' | 'uncertain';
+}
+/**
+ * Durable destination history for unscoped owner messages. It stores only
+ * authenticated CIDs, wire IDs, timestamps and content digests; never bodies,
+ * filenames or display names. A pre-send marker prevents blind replay after a
+ * crash or transport ambiguity.
+ */
+export declare class OwnerConversationState {
+    private readonly path;
+    private conversations;
+    private sends;
+    private corruptReason?;
+    constructor(path: string);
+    integrity(): {
+        ok: boolean;
+        error?: string;
+    };
+    recordInbound(contact: string, wireId: string, now?: number): void;
+    remove(contact: string): void;
+    route(effective: Set<string>): {
+        contact: string;
+        basis: OwnerConversationRouteBasis;
+    };
+    beginSend(contact: string, digest: string, now?: number, minIntervalMs?: number, dedupe?: 'contact' | 'all'): OwnerProactiveSend;
+    finishSend(id: string, status: 'delivered' | 'uncertain'): void;
+    private mutate;
+    private persist;
+    private assertHealthy;
+    private validConversation;
+    private validSend;
+}
 export type OwnerSource = 'baseline' | 'dynamic';
 export interface OwnerEntry {
     cid: string;
@@ -36,9 +77,13 @@ export declare class OwnerAuthorizationState {
     entries(): OwnerEntry[];
     authorize(cid: string): OwnerEntry;
     revoke(cid: string): OwnerEntry;
+    private inBaseline;
+    private hasCanonical;
+    private deleteCanonical;
     private assertHealthy;
     private record;
     private snapshot;
     private restore;
     private persist;
 }
+export {};