@kingcrab/pi-imessage 0.0.43 → 1.1.0

package/dist/agent/progress.js

@@ -0,0 +1,173 @@
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { isReplyEnabled, readSettings } from "../config/settings.js";
+import { Chats, progressEnabled } from "./chats.js";
+import { takeScheduledCompaction } from "./compaction.js";
+import { deliverDirect } from "./direct-send.js";
+import { argumentSummary, commandPreview, formatProgress } from "./progress-format.js";
+import { Runs } from "./run.js";
+async function calledTool(harness, task) {
+    if (task.kind !== "pi.tool")
+        return;
+    // The registered native task owns this input shape and its branded assistant ID.
+    const input = task.input;
+    // Nested calls belong to a parent tool; only model-issued calls get progress notices.
+    if (input.kind !== "model")
+        return;
+    const entry = await harness.commit((tx) => tx.entry(input.assistant), BACKGROUND_CONTEXT);
+    const message = entry?.model?.[0];
+    if (message?.role !== "assistant")
+        return;
+    const call = message.content.find((part) => part.type === "toolCall" && part.id === input.callId);
+    return call?.type === "toolCall" ? call : undefined;
+}
+async function canonicalPath(path) {
+    return realpath(path).catch(async () => resolve(await realpath(dirname(path)).catch(() => dirname(path)), basename(path)));
+}
+/** Classify metadata only; attachment reads still execute and keep their normal results/history. */
+async function attachmentPath(workingDir, path) {
+    if (typeof path !== "string")
+        return false;
+    // Match the native read tool's @, Unicode-space and home-path normalization.
+    let normalized = path.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ");
+    if (normalized.startsWith("@"))
+        normalized = normalized.slice(1);
+    if (normalized === "~" || normalized.startsWith("~/"))
+        normalized = resolve(homedir(), normalized.slice(2));
+    if (normalized.startsWith("file://")) {
+        try {
+            normalized = fileURLToPath(normalized);
+        }
+        catch {
+            /* Keep malformed URLs as ordinary paths, like native read. */
+        }
+    }
+    const root = resolve(workingDir, "attachments");
+    const candidate = resolve(workingDir, normalized);
+    const roots = [root, await canonicalPath(root)];
+    const candidates = [candidate, await canonicalPath(candidate)];
+    return roots.some((directory) => candidates.some((file) => file === directory || file.startsWith(`${directory}${sep}`)));
+}
+/** Observe native admission and settlement; Durable owns execution and recovery. */
+export async function startProgress(harness, workingDir, sender) {
+    // Existing live work belongs to the previous startup; do not replay historical progress.
+    const seen = new Set((await harness.inspect(BACKGROUND_CONTEXT)).tasks.map(({ record }) => record.id));
+    const active = new Map();
+    let pending = Promise.resolve();
+    async function notify(task, notice) {
+        if (task.kind === "pi.compaction" && (await takeScheduledCompaction(harness, task.id)))
+            return;
+        const settings = await readSettings(workingDir);
+        const chats = (await harness.snapshot(Chats, BACKGROUND_CONTEXT))?.items ?? [];
+        // Nothing can be enabled when the global setting is off and no chat chose /verbose on.
+        if (!settings.progressMessages && !chats.some((chat) => chat.progress))
+            return;
+        const runs = (await harness.snapshot(Runs, BACKGROUND_CONTEXT))?.items ?? [];
+        let conversationId = task.conversationId;
+        let chatGuid;
+        const parents = [];
+        while (!chatGuid) {
+            chatGuid = [...chats, ...runs].find((item) => item.conversationId === conversationId)?.chatGuid;
+            if (chatGuid)
+                break;
+            const conversation = await harness.commit((tx) => tx.conversation(conversationId), BACKGROUND_CONTEXT);
+            if (!conversation?.owner)
+                return; // Health and unrelated ownerless conversations stay local.
+            const owner = await harness.getTask(conversation.owner.taskId, BACKGROUND_CONTEXT);
+            const call = owner && (await calledTool(harness, owner));
+            parents.unshift(call?.name ?? owner?.kind ?? "child");
+            conversationId = conversation.owner.conversationId;
+        }
+        if (!isReplyEnabled(settings, chatGuid) || !progressEnabled(settings, chats, chatGuid))
+            return;
+        const tool = await calledTool(harness, task);
+        if (tool?.name === "read" && (await attachmentPath(workingDir, tool.arguments.path)))
+            return;
+        const request = tool
+            ? {
+                phase: "request",
+                type: "tool",
+                parents,
+                name: tool.name,
+                ...(tool.name === "bash"
+                    ? { commandPreview: commandPreview(tool.arguments.command) }
+                    : { summary: argumentSummary(tool.arguments) }),
+            }
+            : { phase: "request", type: "task", parents, name: task.kind };
+        notice.chatGuid = chatGuid;
+        notice.request = request;
+        const text = formatProgress(request);
+        const receipt = await deliverDirect(harness, { chatGuid, requestId: `progress:${task.id}`, text }, sender);
+        if (receipt.textStatus === "unknown")
+            console.warn("Progress delivery unknown", task.id, chatGuid);
+    }
+    async function settled(task, notice, elapsed) {
+        if (!notice.chatGuid || !notice.request || task.state.status !== "terminal")
+            return;
+        const settings = await readSettings(workingDir);
+        const chats = (await harness.snapshot(Chats, BACKGROUND_CONTEXT))?.items ?? [];
+        if (!isReplyEnabled(settings, notice.chatGuid) || !progressEnabled(settings, chats, notice.chatGuid))
+            return;
+        const outcome = task.state.outcome;
+        let success = outcome.status === "completed";
+        if (success && task.kind === "pi.tool" && outcome.status === "completed") {
+            const result = outcome.result;
+            const entryId = result && typeof result === "object" && "entryId" in result ? result.entryId : undefined;
+            const entry = typeof entryId === "number"
+                ? await harness.commit((tx) => tx.entry(entryId), BACKGROUND_CONTEXT)
+                : undefined;
+            const message = entry?.model?.[0];
+            success = message?.role === "toolResult" && !message.isError;
+        }
+        const text = formatProgress({ ...notice.request, phase: "response", success, elapsedMs: elapsed });
+        const receipt = await deliverDirect(harness, {
+            chatGuid: notice.chatGuid,
+            requestId: `progress:${task.id}:done`,
+            text,
+        }, sender);
+        if (receipt.textStatus === "unknown")
+            console.warn("Progress completion delivery unknown", task.id, notice.chatGuid);
+    }
+    const unsubscribe = harness.subscribeCommits(({ changes }) => {
+        for (const change of changes) {
+            if (change.type !== "task" || change.value.kind === "pi.generation")
+                continue;
+            const task = change.value;
+            if (task.state.status === "terminal") {
+                seen.delete(task.id);
+                const notice = active.get(task.id);
+                active.delete(task.id);
+                if (notice) {
+                    const elapsed = performance.now() - notice.admittedAt;
+                    pending = pending
+                        .then(() => settled(task, notice, elapsed))
+                        .catch((error) => {
+                        console.warn("Progress completion notification failed", task.id, error);
+                    });
+                }
+                continue;
+            }
+            if (task.state.status !== "pending" || seen.has(task.id))
+                continue;
+            seen.add(task.id);
+            const notice = { admittedAt: performance.now() };
+            active.set(task.id, notice);
+            // The synchronous observer must not call Session APIs or block adoption.
+            pending = pending
+                .then(() => notify(task, notice))
+                .catch((error) => {
+                console.warn("Progress notification failed", task.id, error);
+            });
+        }
+    });
+    return {
+        flush: () => pending,
+        async close() {
+            unsubscribe();
+            await pending;
+        },
+    };
+}

package/dist/agent/prompt.js

@@ -0,0 +1,79 @@
+import { DefaultPackageManager, formatSkillsForPrompt, loadProjectContextFiles, loadSkills, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { defineExtension, section } from "@earendil-works/pi-durable";
+function preamble(workingDir) {
+    return `You are the user's best friend communicating via iMessage. Be concise. No emojis.
+
+## Context
+- Plain text only. Do not use Markdown formatting, double asterisks (**like this**), or [markdown](links).
+- Reply in the same language the user is writing in.
+- Name sources without URLs by default to avoid iMessage link previews. Include original URLs only when the user asks for links.
+- Output ONLY the final message to the user. Never include planning, reasoning, analysis or meta-commentary in the reply.
+
+## Environment
+You are running directly on the host machine.
+- Bash working directory: ${workingDir}
+- Be careful with system modifications.
+
+## Workspace Layout
+${workingDir}/
+├── settings.json                # Bot configuration
+├── extensions/<name>/           # Trusted business tools/tasks: index.ts and config.json
+├── skills/                      # Your reusable CLI tools; skills/file-memory is the memory store
+├── attachments/<chat>/          # Files users shared, referenced by path in messages
+└── durable/                     # All conversations (JSONL); grep here to search old messages
+
+## Messaging
+Your final answer is sent to the chat automatically. Use the send_message tool for files or extra messages.
+Six-hour compaction and workspace extension schedules run as native Durable background tasks. Their deadlines and recent execution records are visible on the read-only Scheduled web page.
+You can create or update a trusted workspace extension in extensions/<name>/index.ts with its config.json, using the host-pinned Durable primitives. An extension can define multiple tasks and optional daily/interval schedules. Use reload_extensions (or the user command /reload) to apply code and configuration changes without interrupting current calls or resetting saved deadlines.
+
+## Long-running work
+- On a resumed or interrupted task, check its transcript and actual results first. An interrupted tool may already have acted: verify it instead of blindly repeating it.
+
+## Skills (custom CLI tools)
+Create reusable tools for on-demand tasks in ${workingDir}/skills/<name>/, each with a SKILL.md:
+---
+name: skill-name
+description: What this skill does
+---
+Usage instructions and details here.`;
+}
+/**
+ * The system prompt: product instructions, AGENTS files and skills, read once per load.
+ * `/reload` builds it again; the same extension name replaces the old one in place.
+ */
+export async function loadPrompt(workingDir, agentDir) {
+    const settings = SettingsManager.create(workingDir, agentDir, { projectTrusted: false });
+    const packages = new DefaultPackageManager({ cwd: workingDir, agentDir, settingsManager: settings });
+    // Discover installed user resources only; never install packages or execute SDK extensions headlessly.
+    const resources = await packages.resolve(async (source) => {
+        console.warn("Prompt resource unavailable; skipping missing package", source);
+        return "skip";
+    });
+    const agents = loadProjectContextFiles({ cwd: workingDir, agentDir });
+    const loadedSkills = loadSkills({
+        cwd: workingDir,
+        agentDir,
+        includeDefaults: false,
+        skillPaths: resources.skills
+            .filter((resource) => resource.enabled && resource.metadata.scope === "user")
+            .map((resource) => resource.path),
+    });
+    for (const diagnostic of loadedSkills.diagnostics)
+        console.warn("Skill resource diagnostic", diagnostic);
+    const skills = formatSkillsForPrompt(loadedSkills.skills, "read").trim();
+    const text = preamble(workingDir);
+    return defineExtension({
+        name: "prompt",
+        sections: [
+            section("preamble", () => text, { tag: false }),
+            section("project_context", () => agents.length === 0
+                ? undefined
+                : [
+                    "Project-specific instructions and guidelines:",
+                    ...agents.map(({ path, content }) => `<project_instructions path="${path}">\n${content}\n</project_instructions>`),
+                ].join("\n\n")),
+            section("skills", (input) => input.agent.tools.some((tool) => tool.name === "read") ? skills || undefined : undefined),
+        ],
+    });
+}

package/dist/agent/replies.js

@@ -0,0 +1,10 @@
+import { defineDoc } from "@earendil-works/pi-durable";
+export const Deliveries = defineDoc({
+    kind: "imessage.deliveries",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "initial",
+    initial: () => ({ answers: {} }),
+    checkpointWhen: () => false,
+});

package/dist/agent/run.js

@@ -0,0 +1,160 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { Type } from "@earendil-works/pi-ai";
+import { AssistantEntry, configure, defineDoc, defineExtension, defineTask, defineTool, GenerationTask, hook, InboxDoc, LiveDoc, section, } from "@earendil-works/pi-durable";
+import { finalReplyText } from "../extensions/final-text.js";
+import { Deliveries } from "./replies.js";
+/** Every `/run`; ended runs stay listed so their last answers can still be delivered. */
+export const Runs = defineDoc({
+    kind: "imessage.runs",
+    version: 1,
+    scope: "session",
+    initial: () => ({ items: [] }),
+    checkpointWhen: () => false,
+});
+/** Model-visible notes in the chat conversation about what happened in a run. */
+export const RUN_RECORD = "imessage.run-record";
+export function activeRun(runs, chat) {
+    return runs?.find((run) => run.chat === chat && run.status === "active");
+}
+export function runRecord(text, now) {
+    return { kind: RUN_RECORD, model: [{ role: "user", content: text, timestamp: now }] };
+}
+const instructions = [
+    "This conversation is a /run: the user asked you to keep working on the task without waiting for confirmation.",
+    "Every final answer is sent to the chat as it is written.",
+    "Call end_run when the task is done, when you need the user, or when there is no unfinished task; do not invent a new task.",
+].join("\n");
+async function finish(tx, taskId, stopped, now) {
+    const run = (await tx.doc(Runs)).items.find((item) => item.taskId === taskId);
+    if (!run || run.status === "ended")
+        return;
+    if (stopped) {
+        // Withdraw answers that were not claimed for sending; a claimed send cannot be retracted.
+        const deliveries = await tx.doc(Deliveries, run.conversationId);
+        const entries = await tx.scanEntries({
+            conversationId: run.conversationId,
+            ...(deliveries.scanned === undefined ? {} : { minEntryId: deliveries.scanned }),
+        }, 1000);
+        for (const entry of entries.items) {
+            const key = String(entry.id);
+            if (!AssistantEntry.is(entry) || !finalReplyText(entry.model?.[0]) || deliveries.answers[key])
+                continue;
+            if (deliveries.drafts?.[key] && deliveries.drafts[key].status !== "held")
+                continue;
+            deliveries.drafts ??= {};
+            deliveries.drafts[key] = { status: "cancelled" };
+        }
+        const drafts = deliveries.drafts ?? {};
+        for (const [key, draft] of Object.entries(drafts))
+            if (draft.status === "held")
+                drafts[key] = { status: "cancelled" };
+        run.endReason = "stopped";
+    }
+    run.endReason ??= now >= run.deadline ? "deadline" : "finished";
+    run.status = "ended";
+    // The chat conversation is idle while its run is active: ordinary messages go to the run.
+    await tx.appendEntry(run.chat, runRecord(`[/run ended: ${run.endReason}]`, now));
+}
+/** Owns the run conversation, so aborting it stops the run's work and withdraws its queued messages. */
+export const RunTask = defineTask({
+    name: "imessage.run",
+    version: 1,
+    initial: () => ({ phase: "start" }),
+    phases: {
+        async start(task, runtime, context) {
+            const run = (await runtime.snapshot(Runs, context))?.items.find((item) => item.taskId === task.id);
+            const conversation = run && (await runtime.conversation(run.conversationId, context));
+            if (!conversation)
+                throw new Error("Run conversation is missing");
+            await conversation.submit({ type: "input", content: task.input.task, requestId: `run:${task.id}`, whenBusy: "steer" }, context);
+            await runtime.commit(() => ({ status: "running", checkpoint: { phase: "watch" } }), context);
+        },
+        async watch(task, runtime, context) {
+            const run = (await runtime.snapshot(Runs, context))?.items.find((item) => item.taskId === task.id);
+            const conversation = run && (await runtime.conversation(run.conversationId, context));
+            // onYield keeps the run conversation busy until end_run or the deadline; idle means the run is over.
+            await conversation?.waitForIdle(context);
+            await runtime.commit(async (tx) => {
+                await finish(tx, task.id, false, runtime.now());
+                return { status: "terminal", outcome: { status: "completed", result: null } };
+            }, context);
+        },
+    },
+    async abort(task, runtime, context) {
+        await runtime.commit(async (tx) => {
+            await finish(tx, task.id, true, runtime.now());
+            return { status: "terminal", outcome: { status: "aborted" } };
+        }, context);
+    },
+});
+/** Selected only by run conversations; its task definition resolves everywhere. */
+export const RunExtension = defineExtension({
+    name: "run",
+    tasks: [RunTask],
+    sections: [section("run", () => instructions)],
+    tools: [
+        defineTool({
+            name: "end_run",
+            description: "End this /run when the task is done, you need the user, or nothing is left to do.",
+            parameters: Type.Object({ reason: Type.String() }),
+            replay: "safe",
+            async execute(args, api, context) {
+                await api.commit(async (tx) => {
+                    const run = (await tx.doc(Runs)).items.find((item) => item.conversationId === api.conversationId && item.status === "active");
+                    if (run)
+                        run.endReason = args.reason;
+                }, context);
+                return { output: [{ type: "text", text: "The run ends after this answer." }] };
+            },
+        }),
+    ],
+    hooks: [
+        hook(GenerationTask, {
+            async onYield(_answer, api, context) {
+                const run = (await api.snapshot(Runs, context))?.items.find((item) => item.conversationId === api.conversationId);
+                if (run?.status !== "active" || run.endReason !== undefined)
+                    return;
+                // The deadline only stops continuation; a turn in progress finishes.
+                const minutes = Math.floor((run.deadline - Date.now()) / 60000);
+                if (minutes < 1)
+                    return;
+                return {
+                    continue: `Continue the /run task. ${minutes} minutes left. Call end_run when it is done or you need the user.`,
+                };
+            },
+        }),
+    ],
+});
+/** Starts a run in a fork of the idle chat conversation, or moves the deadline of the active one. */
+export function startRun(chat, chatGuid, deadline, task) {
+    return chat.commit(async (tx) => {
+        const newest = (await tx.scanEntries({ conversationId: chat.id }, 1)).items[0];
+        const runs = await tx.doc(Runs);
+        const active = activeRun(runs.items, chat.id);
+        if (active) {
+            active.deadline = deadline;
+            return { status: "updated", run: { ...active } };
+        }
+        const inbox = await tx.doc(InboxDoc, chat.id);
+        if ((await tx.doc(LiveDoc, chat.id)).run || inbox.items.length > 0)
+            return { status: "busy" };
+        const taskId = await tx.createTask(RunTask, { task }, { ownership: { kind: "conversation" } });
+        const ownership = { ownership: { kind: "task", taskId } };
+        // A fork inherits the chat's context without copying or summarizing it.
+        const conversation = newest
+            ? await tx.forkConversation(chat.id, newest.id, ownership)
+            : await tx.createConversation(ownership);
+        await configure(tx, conversation.id, { extensions: { add: [RunExtension] } });
+        const run = {
+            chatGuid,
+            chat: chat.id,
+            conversationId: conversation.id,
+            taskId,
+            deadline,
+            status: "active",
+        };
+        runs.items.push(run);
+        await tx.appendEntry(chat.id, runRecord(`[/run started: ${task}]`, Date.now()));
+        return { status: "started", run: { ...run } };
+    }, BACKGROUND_CONTEXT);
+}