@kingcrab/pi-imessage 0.0.42 → 1.0.0

package/README.md

@@ -1,70 +1,55 @@
-# @kingcrab/pi-imessage
+# pi-imessage
 
-A minimal and self-managing iMessage bot — powered by [pi](https://github.com/badlogic/pi-mono).
+A minimal, self-managing iMessage bot powered by [Pi Durable](https://github.com/earendil-works/pi/tree/main/packages/durable).
 
-<img height="420" src="https://raw.githubusercontent.com/daya0576/pi-imessage/main/docs/screenshot.png" />
+<img height="420" src="docs/screenshot.png" />
 
-# Features
-- **Minimal**: No BlueBubble, no webhooks, no extra dependencies
-- **Self-managing**: Turn the agent into whatever you need. He builds his own tools without pre-built assumptions
-- **Transparent**: tool calls and reasoning are sent to your iMessage chat, so you can see exactly what it's doing and why
-- **iMessage Integration**: Responds to DMs, SMS, and group chats; identifies who sent each message; understands quoted/reply-to messages
-- **Web UI**: browse chat history, toggle replies on/off per chat, live updates — disable with WEB_ENABLED=false and let the agent build your own web UI
+## Features
 
-# Get Started
+- **Minimal**: No BlueBubbles or webhook setup. Runs directly on your Mac alongside Messages.app.
+- **Messages**: DMs, SMS, and group chats, with sender identification and reply context.
+- **Self-managing**: The agent builds its own tools, with native web search, page fetch, and a [conversation-owned browser](docs/browser.md).
+- **Web UI**: Chat history, native task state, scheduled jobs with their latest ten executions, logs, memory, and configuration.
+- **Memory**: Searchable, traceable records; corrections preserve history. See [structured memory](docs/memory.md).
 
-> ⚠️ **Security note**
-> - Replies are **off** for all chats by default (`blacklist: ["*"]`) — only explicitly whitelisted chats get a response
-> - The agent runs with Full Disk Access and can read/write your filesystem as part of its tool use
-> - The web UI has no authentication and is accessible to anyone on your local network; set `WEB_ENABLED=false` if that's a concern
+## Quick Start
 
-Prerequisites: macOS with Messages.app, Full Disk Access for the terminal, [Pi Coding Agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#quick-start) authenticated
+> Just point your Pi coding agent at this README and ask it to set up pi-imessage.
+
+Prerequisites: macOS with Messages.app, Node.js 22.22.2 or newer, Python 3
+(shared memory writer), Full Disk Access for the terminal, and an authenticated
+[Pi Coding Agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#quick-start).
 
 ```bash
 npm install -g @kingcrab/pi-imessage
 
 pi-imessage             # run in foreground
-pi-imessage install     # install as launchd service (auto-start on boot, restart on crash)
+pi-imessage install     # write a launchd job; loading it is a separate operator action
 ```
 
-# Usage
-
-## Web UI
-
-Available at `http://localhost:7750` (configurable via `WEB_HOST` and `WEB_PORT`).
-
-- Chat history with live updates
-- Logs (tail -f style)
-- Memory (global & per-chat)
-
-P.S. Disable with `WEB_ENABLED=false` and let the agent build your own web UI
-
-## API
-
-The agent is aware of these endpoints via its system prompt and can use them as tools (e.g., scheduling a cron job that calls `/prompt`).
-
-| Endpoint | Description | Example |
-|---|---|---|
-| `POST /send` | Send text and/or a local file attachment to a chat (bypasses the agent) | `curl -X POST localhost:7750/send -d '{"chatGuid": "iMessage;-;+11234567890", "text": "hello"}'`<br>→ `{"ok": true}` |
-| `POST /prompt` | Feed a prompt to the agent asynchronously; replies are sent to the chat when ready | `curl -X POST localhost:7750/prompt -d '{"chatGuid": "iMessage;-;+11234567890", "prompt": "say hello"}'`<br>→ `{"ok": true}` |
-| `GET /health/model` | Make a live request to the configured default AI model; returns HTTP 200 when healthy or 503 on failure | `curl localhost:7750/health/model`<br>→ `{"ok":true,"model":"openai/gpt-5","latencyMs":842,"checkedAt":"..."}` |
+Enable replies for your chats by adding their GUIDs to the [settings allowlist](#settings).
+For installation and service operations, see [ops/README.md](ops/README.md).
 
 ## Commands
 
-Send these as iMessage to interact with the bot:
+Send these commands as iMessages:
 
-| Command | Description | Example Reply |
-|---|---|---|
-| `/help` | List available slash commands | `Commands:`<br>`/help — list commands` |
-| `/new` | Reset the session, starting a fresh conversation | `✓ New session started` |
-| `/status` | Show session stats: tokens, context, model | `💬 3 msgs - ↑7.2k ↓505 1.1%/128k`<br>`🤖 anthropic/claude-sonnet-4 • 💭 minimal` |
-| `/compact` | Compress session context to free up token space | `✓ Compacted: 15.2k → 2.1k tokens` |
-| `/stop` | Steer the agent to stop after current tool calls finish, then process the next queued message | |
-| `/reload` | Reload models and clear all sessions | `✓ Models reloaded` |
+| Command | Description |
+|---|---|
+| `/help` | List commands |
+| `/new` | Cancel current work and start a fresh conversation |
+| `/status` | Show tokens, context usage, and model |
+| `/thinking <level\|default>` | Set thinking for this chat or follow the default |
+| `/compact` | Compress context without replaying prior work |
+| `/run <duration> [task]` | Keep working for up to the given time, e.g. `/run 1h`; `/stop` ends it early |
+| `/stop` | Abort current work and stop `/run`; later messages are still answered |
+| `/reload` | Refresh models/auth, AGENTS, skills and extensions without cancelling work |
 
-## Settings (`WORKING_DIR/settings.json`)
+## Configuration
 
-All fields are optional.
+### Settings
+
+Edit `WORKING_DIR/settings.json`. All fields are optional.
 
 ```json
 {
@@ -79,72 +64,80 @@ All fields are optional.
 }
 ```
 
-**Chat allowlist** controls which chats receive replies (messages are always logged). By default, replies are **off** for all chats (`blacklist: ["*"]`) — opt in specific chats via the web UI or by adding their guid to `whitelist`. Resolution priority: `blacklist[guid]` > `whitelist[guid]` > `blacklist["*"]` > `whitelist["*"]`.
+Add chat GUIDs to `whitelist` to enable replies; `blacklist: ["*"]` blocks replies
+elsewhere. An explicit blacklist entry takes priority. Messages are always logged.
+Rich text is optional; `markdown: true` renders bold spans in direct iMessage chats.
 
-**Rich text** is optional and disabled by default. When enabled, pi-imessage uses a UI automation fallback to open the target conversation, paste an RTF payload, and send it. Currently this is intended for direct-message iMessage chats. With `markdown: true`, pi-imessage interprets `**bold**` spans and renders them as actual bold text in Messages.
+### Workspace extensions and scheduler
 
-## Environment Variables
+Context compaction runs every six hours as a native Durable background task.
+Personal tools, tasks and optional daily/interval schedules live in
+`WORKING_DIR/extensions/<name>/index.ts` with `config.json`, not framework
+settings. Startup and `/reload` load them; the assistant can use
+`reload_extensions` to apply its own changes.
 
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `WEB_ENABLED` | no | `true` | Set to `false` to disable the built-in web UI |
-| `WEB_HOST` | no | `localhost` | Web UI host |
-| `WEB_PORT` | no | `7750` | Web UI port |
-| `WORKING_DIR` | no | `~/.pi/imessage` | Workspace directory |
-| `AGENT_IDLE_TIMEOUT_MS` | no | `120000` | Abort only after this much continuous agent inactivity; model and tool events reset the timer |
-| `AGENT_MAX_PROMPT_DURATION_MS` | no | `1800000` | Absolute ceiling for one prompt, independent of activity |
+See [workspace extensions](docs/workspace-extensions.md) for the factory contract
+and scheduling rules.
+One-off runs use the same scheduler: declare a stable `runRequests` ID, target
+schedule and `at: "now"` (or epoch milliseconds) in the extension configuration,
+then call `reload_extensions`. No restart or separate execution API is needed.
 
-# Development
+Times use the service machine's local timezone. Saved deadlines survive reload
+and restart; view schedules and latest-ten execution history at `/scheduled`.
 
-```bash
-npm run check        # typecheck + lint (run after code changes)
-npm test             # run tests
-```
+### Model policy
 
-# How It Works
+Optional `settings.json` fields, applied at startup and `/reload`:
 
+```json
+{
+  "modelPolicy": {
+    "fallback": { "provider": "your-provider", "modelId": "your-model" },
+    "codexServiceTier": "default"
+  }
+}
 ```
-  ~/Library/Messages/chat.db
-        │
-  (poll every 2s for new rows)
-        │
-        ▼
-┌──────────────────────────────────────────────────┐
-│              pi-imessage                         │
-│                                                  │
-│  Watcher (chat.db polling)                       │
-│    │                                             │
-│    ├─ Filter: is_from_me=0, no reactions         │
-│    ├─ Deduplicate via seenRowIds                 │
-│    ├─ Read attachments from local disk           │
-│    │                                             │
-│    ▼                                             │
-│  AsyncQueue<IncomingMessage>                     │
-│    │                                             │
-│    ▼                                             │
-│  SessionManager (pi-coding-agent)                │
-│    │  per chatGuid, persistent on disk           │
-│    │  └─ data/<chatGuid>/                        │
-│    │       ├─ log.jsonl      (full history)      │
-│    │       └─ context.jsonl  (LLM context)       │
-│    │                                             │
-│    ▼                                             │
-│  Agent loop (pi-agent-core)                      │
-│    │                                             │
-│    │  ┌─ outer: follow-up messages ────┐         │
-│    │  │  ┌─ inner: tool calls +      ┐ │         │
-│    │  │  │  steering messages        │ │         │
-│    │  │  └───────────────────────────┘ │         │
-│    │  └────────────────────────────────┘         │
-│    │                                             │
-│    ▼                                             │
-│  Collect assistant reply text                    │
-│    │                                             │
-│    ├─ sendMessage (AppleScript → Messages.app)   │
-│    └─ save logs (messages, digests)              │
-│                                                  │
-└──────────────────────────────────────────────────┘
-        │
-        ▼
-  iMessage (user receives reply via Messages.app)
+
+Without a fallback, an unavailable default fails explicitly. Without a tier,
+provider requests are unchanged. `codexServiceTier` accepts `default` or
+`priority`; priority may have a different cost. Existing deployments migrate
+their previous choices into explicit configuration rather than silently changing
+behavior.
+
+### Environment Variables
+
+All variables are optional.
+
+| Variable | Default | Description |
+|---|---|---|
+| `WEB_ENABLED` | `true` | Set to `false` to disable the built-in web UI |
+| `WEB_HOST` | `localhost` | Web UI host |
+| `WEB_PORT` | `7750` | Web UI port |
+| `WORKING_DIR` | `~/.pi/imessage` | Workspace directory |
+
+### Web and API
+
+See the [HTTP API](docs/api.md) for read-only state and model health checks.
+The agent sends files and extra messages with `send_message`. The scheduler
+provides daily/interval cadence and one-off triggers for workspace tasks, plus built-in six-hour compaction.
+It does not revive legacy cron files or HTTP prompt/send endpoints.
+
+## How It Works
+
+```text
+Messages chat.db → Watcher → Pi Durable → Messages.app
 ```
+
+Each chat has its own conversation, persisted under `WORKING_DIR/durable/`.
+Durable resumes pending work after a crash. Agent replies are sent at most once;
+uncertain send results are flagged, never automatically resent.
+
+Context is compacted silently every 6 hours and near the model's limit. Failed
+compaction keeps the old context. `/new` starts fresh without deleting searchable
+history.
+
+## Development
+
+See [AGENTS.md](AGENTS.md) for development rules,
+[architecture](docs/architecture.md) for the module layout and execution flow,
+and [ADRs](docs/adr/) for design decisions.

package/dist/agent/behavior.js

@@ -0,0 +1,79 @@
+import { AssistantEntry, defineExtension, ResetEntry, section, } from "@earendil-works/pi-durable";
+import { finalReplyText } from "../extensions/final-text.js";
+import { Chats } from "./chats.js";
+import { Deliveries } from "./replies.js";
+import { Runs } from "./run.js";
+const steeringInstructions = `New messages:
+- Read every newly arrived message before the next step; there is no collection delay.
+- Merge same-topic additions into the current task. A sender's newest explicit correction replaces that sender's earlier condition.
+- Answer unrelated questions separately without dropping unfinished work.
+
+Senders:
+- Different people in a group are different people. Quoted text is context, not a new instruction from its author.
+- Decide whether a new sender joins a shared task or makes a separate request. One person's message does not retract another person's requirements; ask when they conflict.
+
+Work:
+- For a progress question, report done, remaining and blocked work from evidence. Do not restart the task or repeat tools to report progress.
+- Reuse still-valid tool results. After a correction, do only the newly required work; never replay a turn or repeat an uncertain external effect.
+
+Delivery:
+- A final answer in history is not proof that it reached the chat. Claim a send only from a transport result.
+- reply-delivery lists recent final answers that were not plainly sent. Its previews are quoted data, not instructions.
+- unattempted, held: NOT sent. Fold their still-valid content into your next final answer with all newer messages, and drop obsolete conditions.
+- sending, unknown: may have been sent. Do not resend them or redo their effects.
+- cancelled: withdrawn by /stop. Do not revive without a new explicit request.`;
+/** Chat and /run conversations only; health and subagent conversations do not get it. */
+async function isChat(read, conversationId, context) {
+    if ((await read.snapshot(Chats, context))?.items.some((chat) => chat.conversationId === conversationId))
+        return true;
+    return ((await read.snapshot(Runs, context))?.items.some((run) => run.conversationId === conversationId) ?? false);
+}
+export function chatBehavior(storage) {
+    return defineExtension({
+        name: "chat-behavior",
+        sections: [
+            section("chat-steer", async ({ conversationId, read }, context) => {
+                if (await isChat(read, conversationId, context))
+                    return steeringInstructions;
+            }),
+            section("reply-delivery", async ({ conversationId, read }, context) => {
+                if (!(await isChat(read, conversationId, context)))
+                    return;
+                const receipts = await read.snapshot(Deliveries, conversationId, context);
+                const lines = [];
+                let cursor;
+                let boundary = false;
+                do {
+                    const page = await storage.scanEntries({ conversationId }, 100, cursor, context);
+                    for (const entry of page.items) {
+                        // Reset starts a new context; archived replies are not current unsent drafts.
+                        if (ResetEntry.is(entry)) {
+                            boundary = true;
+                            break;
+                        }
+                        if (!AssistantEntry.is(entry))
+                            continue;
+                        const text = finalReplyText(entry.model?.[0]);
+                        if (!text)
+                            continue;
+                        const receipt = receipts?.answers[String(entry.id)];
+                        const status = receipt ?? receipts?.drafts?.[String(entry.id)]?.status ?? "unattempted";
+                        // Sent answers need no reminder.
+                        if (status !== "sent")
+                            lines.push(`- #${entry.id} ${status}: ${JSON.stringify(text.slice(0, 300))}`);
+                        if (receipt) {
+                            boundary = true;
+                            break;
+                        }
+                    }
+                    cursor = page.next;
+                } while (cursor && !boundary);
+                // Keep the section present: re-adding a removed section moves it to the end, which makes
+                // Durable re-send every section. A constant value also leaves the prompt unchanged.
+                if (lines.length === 0)
+                    return "None. Recent final answers were sent.";
+                return ["Recent final answers not plainly sent, oldest first:", ...lines.reverse()].join("\n");
+            }),
+        ],
+    });
+}

package/dist/agent/chats.js

@@ -0,0 +1,67 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { configure, defineDoc, UserEntry, } from "@earendil-works/pi-durable";
+import { activeRun, Runs } from "./run.js";
+export const Chats = defineDoc({
+    kind: "imessage.chats",
+    version: 1,
+    scope: "session",
+    initial: () => ({ items: [] }),
+});
+export const WatchCursor = defineDoc({
+    kind: "imessage.watch-cursor",
+    version: 1,
+    scope: "session",
+    initial: () => ({}),
+});
+export function formatInput(input) {
+    let prefix = "";
+    if (input.sender !== undefined) {
+        if (input.chatGuid.includes(";+;"))
+            prefix = `[Group '${input.groupName || "unnamed"}' from ${input.sender}] `;
+        else
+            prefix = `[${input.service === "SMS" ? "SMS" : "DM"} from ${input.sender}] `;
+    }
+    const reply = input.replyTo ? `[replying to: "${input.replyTo}"] ` : "";
+    const files = (input.attachments ?? []).map((path) => `\n[Attachment: ${path}]`).join("");
+    return `${prefix}${reply}${input.text}${files}`;
+}
+export async function chatConversation(harness, defaults, chatGuid) {
+    const conversationId = await harness.commit(async (tx) => {
+        const chats = await tx.doc(Chats);
+        const existing = chats.items.find((chat) => chat.chatGuid === chatGuid);
+        if (existing)
+            return existing.conversationId;
+        const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+        await configure(tx, conversation.id, defaults);
+        chats.items.push({ chatGuid, conversationId: conversation.id });
+        return conversation.id;
+    }, BACKGROUND_CONTEXT);
+    const conversation = await harness.conversation(conversationId, BACKGROUND_CONTEXT);
+    if (!conversation)
+        throw new Error("Chat conversation is missing");
+    return conversation;
+}
+export async function submitMessage(harness, defaults, input, reply = true) {
+    // Snapshot before awaiting: callers may reuse their input object.
+    const guid = input.guid;
+    const content = formatInput(input);
+    if (!input.chatGuid.trim() || !guid.trim() || (!input.text.trim() && !input.attachments?.length))
+        throw new Error("Chat GUID, message GUID and content are required");
+    const conversation = await chatConversation(harness, defaults, input.chatGuid);
+    const log = {
+        type: "write",
+        requestId: guid,
+        entry: { kind: UserEntry.kind, model: [{ role: "user", content, timestamp: Date.now() }] },
+    };
+    if (!reply)
+        return conversation.submit(log, BACKGROUND_CONTEXT);
+    const message = { type: "input", content, requestId: guid, whenBusy: "steer" };
+    const run = activeRun((await harness.snapshot(Runs, BACKGROUND_CONTEXT))?.items, conversation.id);
+    const target = run && (await harness.conversation(run.conversationId, BACKGROUND_CONTEXT));
+    if (!target)
+        return conversation.submit(message, BACKGROUND_CONTEXT);
+    // During a run, the chat has one place where work happens; its own conversation keeps the record.
+    const submission = await target.submit(message, BACKGROUND_CONTEXT);
+    await conversation.submit(log, BACKGROUND_CONTEXT);
+    return submission;
+}

package/dist/agent/commands.js

@@ -0,0 +1,163 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { LiveDoc, UsageDoc, UserEntry, } from "@earendil-works/pi-durable";
+import { chatConversation } from "./chats.js";
+import { activeRun, Runs, startRun } from "./run.js";
+const help = [
+    "/help - list commands",
+    "/new - stop current work and start an empty context",
+    "/status - show messages, tokens, context usage, model and run",
+    "/compact [instructions] - compress context",
+    "/thinking <level|default> - set thinking for this chat",
+    "/reload - reload models, instructions and skills; apply the default model to this chat",
+    "/run <duration> [task] - keep working until done, blocked or the deadline, e.g. /run 1h",
+    "/stop - stop the current work or /run",
+].join("\n");
+const thinkingLevels = ["off", "minimal", "low", "medium", "high", "xhigh"];
+export function isCommand(text) {
+    return text.trimStart().startsWith("/");
+}
+export function parseDuration(value) {
+    const match = /^(?:(\d+)h)?(?:(\d+)m)?$/.exec(value);
+    if (!match || (!match[1] && !match[2]))
+        return;
+    return (Number(match[1] ?? 0) * 60 + Number(match[2] ?? 0)) * 60000;
+}
+function tokens(count) {
+    return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
+}
+export function compactionReply(outcome, placement) {
+    if (outcome.status === "aborted")
+        return "Compaction cancelled.";
+    if (outcome.status !== "completed")
+        return "Compaction failed.";
+    if (outcome.result.entryId !== undefined)
+        return "Compacted.";
+    if (outcome.result.submissionId === undefined)
+        return "Nothing to compact.";
+    if (placement?.type !== "write")
+        return "Compaction result unavailable.";
+    if (placement.status === "done")
+        return "Compacted.";
+    if (placement.status === "queued")
+        return "Compaction summary queued for the next turn boundary.";
+    return placement.reason === "stale"
+        ? "Compaction summary discarded because the context changed."
+        : "Compaction summary was not applied.";
+}
+/** Runs a slash command through Durable APIs; command replies bypass the model. */
+export async function runCommand(options) {
+    const { harness, chatGuid } = options;
+    const [name, ...rest] = options.text.trim().split(/\s+/);
+    const argument = rest.join(" ");
+    const conversation = await chatConversation(harness, options.defaults, chatGuid);
+    const run = activeRun((await harness.snapshot(Runs, BACKGROUND_CONTEXT))?.items, conversation.id);
+    // Agent settings apply to the chat and to its active run.
+    const configure = async (change) => {
+        await conversation.configure(change, BACKGROUND_CONTEXT);
+        if (run)
+            await (await harness.conversation(run.conversationId, BACKGROUND_CONTEXT))?.configure(change, BACKGROUND_CONTEXT);
+    };
+    switch (name) {
+        case "/help":
+            return { reply: help };
+        case "/stop": {
+            if (run) {
+                await harness.abortTask(run.taskId, BACKGROUND_CONTEXT);
+                await harness.waitForTask(run.taskId, BACKGROUND_CONTEXT);
+                await options.closeBrowsers?.(conversation.id);
+                return { reply: "Stopped." };
+            }
+            // Abort the generation that owns the current inputs, not the conversation, so later queued
+            // messages stay in the inbox (ADR 0015). Retry while generation hands the same inputs over.
+            const live = async () => (await harness.snapshot(LiveDoc, conversation.id, BACKGROUND_CONTEXT))?.run;
+            const stopping = await live();
+            if (!stopping) {
+                await options.closeBrowsers?.(conversation.id);
+                return { reply: "Nothing is running." };
+            }
+            for (let current = stopping; current?.inputs[0] === stopping.inputs[0]; current = await live()) {
+                await harness.abortTask(current.taskId, BACKGROUND_CONTEXT);
+                await harness.waitForTask(current.taskId, BACKGROUND_CONTEXT);
+            }
+            await options.closeBrowsers?.(conversation.id);
+            // A passive note gives Durable a boundary to place the queued messages.
+            await conversation.submit({
+                type: "write",
+                entry: {
+                    kind: UserEntry.kind,
+                    model: [{ role: "user", content: "[/stop]", timestamp: Date.now() }],
+                },
+            }, BACKGROUND_CONTEXT);
+            return { reply: "Stopped." };
+        }
+        case "/new":
+        case "/status": {
+            if (name === "/new") {
+                // The run task belongs to the chat conversation, so this abort stops it too.
+                await conversation.abort(BACKGROUND_CONTEXT);
+                await options.closeBrowsers?.(conversation.id);
+                await conversation.reset(undefined, BACKGROUND_CONTEXT);
+            }
+            const agent = await conversation.agent(BACKGROUND_CONTEXT);
+            const context = await conversation.context(BACKGROUND_CONTEXT);
+            const usage = Object.values((await harness.snapshot(UsageDoc, conversation.id, BACKGROUND_CONTEXT))?.models ?? {});
+            const last = context.messages.findLast((message) => message.role === "assistant" && message.usage.totalTokens > 0);
+            const window = agent.model && options.models.getModel(agent.model.provider, agent.model.modelId)?.contextWindow;
+            const used = last?.role === "assistant" ? last.usage.totalTokens : undefined;
+            return {
+                reply: [
+                    [
+                        `${context.messages.filter((message) => message.role === "user").length} msgs -`,
+                        `in ${tokens(usage.reduce((sum, item) => sum + item.input, 0))}`,
+                        `out ${tokens(usage.reduce((sum, item) => sum + item.output, 0))}`,
+                        window
+                            ? `${used === undefined ? "?" : `${((used / window) * 100).toFixed(1)}%`}/${tokens(window)}`
+                            : "",
+                    ]
+                        .join(" ")
+                        .trim(),
+                    `Model: ${agent.model ? `${agent.model.provider}/${agent.model.modelId}` : "unset"}, thinking: ${agent.thinkingLevel}`,
+                    ...(name === "/status"
+                        ? [`Run: ${run ? `until ${new Date(run.deadline).toISOString()}` : "none"}`]
+                        : []),
+                ].join("\n"),
+            };
+        }
+        case "/compact":
+            return {
+                wait: await conversation.compact(argument || undefined, BACKGROUND_CONTEXT),
+            };
+        case "/thinking":
+            if (argument === "default") {
+                await configure({ thinkingLevel: options.defaults.thinkingLevel ?? null });
+                return { reply: "Thinking follows the default." };
+            }
+            if (!thinkingLevels.includes(argument))
+                return { reply: `Usage: /thinking <${thinkingLevels.join("|")}|default>` };
+            await configure({ thinkingLevel: argument });
+            return { reply: `Thinking: ${argument} (this chat only)` };
+        case "/reload": {
+            const current = await options.reload();
+            await configure({ model: current.model });
+            return { reply: `Reloaded. Model: ${current.model.provider}/${current.model.modelId}` };
+        }
+        case "/run": {
+            const duration = parseDuration(rest[0] ?? "");
+            if (!duration)
+                return { reply: "Usage: /run <duration, e.g. 30m or 2h> [task]" };
+            const task = rest.slice(1).join(" ");
+            const started = await startRun(conversation, chatGuid, Date.now() + duration, task || "Continue the current task.");
+            if (started.status === "busy")
+                return { reply: "Busy. Send /run again when the current work is done." };
+            if (started.status === "started")
+                return {};
+            if (task) {
+                const target = await harness.conversation(started.run.conversationId, BACKGROUND_CONTEXT);
+                await target?.submit({ type: "input", content: task, requestId: options.guid, whenBusy: "steer" }, BACKGROUND_CONTEXT);
+            }
+            return { reply: `Run extended until ${new Date(started.run.deadline).toISOString()}.` };
+        }
+        default:
+            return { reply: `Unknown command.\n${help}` };
+    }
+}

package/dist/agent/compaction.js

@@ -0,0 +1,51 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { CompactionEntry, LiveDoc, ResetEntry } from "@earendil-works/pi-durable";
+import { Chats } from "./chats.js";
+// Native compact() uses reason "manual" for both a command and a maintenance tick.
+// Record exact timer task IDs, not conversation IDs, so concurrent manual work stays visible.
+const scheduled = new WeakMap();
+/** Resolve admission before classifying: the commit may be observed before compact() returns its ID. */
+export async function takeScheduledCompaction(harness, taskId) {
+    const state = scheduled.get(harness);
+    if (!state)
+        return false;
+    await Promise.allSettled([...state.admissions]);
+    return state.tasks.delete(taskId);
+}
+/** Admit native compactions, not another summarization loop; Durable decides whether a cut is needed. */
+export async function compactChats(harness, admissionFailed) {
+    const tasks = [];
+    const chats = await harness.snapshot(Chats, BACKGROUND_CONTEXT);
+    for (const chat of chats?.items ?? []) {
+        try {
+            if ((await harness.snapshot(LiveDoc, chat.conversationId, BACKGROUND_CONTEXT))?.compactions?.length)
+                continue;
+            const conversation = await harness.conversation(chat.conversationId, BACKGROUND_CONTEXT);
+            const newest = (await conversation?.entries({}, 1, undefined, BACKGROUND_CONTEXT))?.items[0];
+            if (!conversation || !newest || CompactionEntry.is(newest) || ResetEntry.is(newest))
+                continue;
+            let state = scheduled.get(harness);
+            if (!state) {
+                state = { admissions: new Set(), tasks: new Set() };
+                scheduled.set(harness, state);
+            }
+            const quiet = state;
+            const admission = conversation.compact(undefined, BACKGROUND_CONTEXT).then((taskId) => {
+                quiet.tasks.add(taskId);
+                return taskId;
+            });
+            quiet.admissions.add(admission);
+            try {
+                tasks.push(await admission);
+            }
+            finally {
+                quiet.admissions.delete(admission);
+            }
+        }
+        catch (error) {
+            admissionFailed?.();
+            console.warn("Scheduled compaction admission failed", chat.chatGuid, error);
+        }
+    }
+    return tasks;
+}