@fungi.computer/shiitake-extensions 0.0.0-stage → 0.0.2

package/dist/home/host.js

@@ -0,0 +1,136 @@
+import { Knapsack } from "@fungi.computer/knapsack";
+import { defineCollection, defineExtension, ExtensionCommandError, } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { ask, catalog, done } from "../internal/catalog.js";
+import { Home, homeContract } from "./contract.js";
+import { homeFilesRouting } from "./routing.js";
+/** Hosts admit Home explicitly; no other extension receives the Files slot. */
+export const homeGrant = {
+    id: homeContract.id,
+    capabilities: ["state", "files", "prompt", "projection", "commands"],
+};
+const config = {
+    promptLimit: 4_000,
+    guide: "Home supplies read, list, glob and grep over your default Computer. Bare paths and computer://home/ use Home; computer://<name>/ uses that captured attachment. apply_patch, when offered, uses Home's native patch engine and path jail. Only a person changes Home with /home <name>; ask them when no Home is available.",
+};
+const collections = {
+    choice: defineCollection(Home, { key: () => "default" }),
+};
+/** Agent-scope choice with per-run tools and prompt over one captured table. */
+export function homeExtension(options) {
+    // Core retains one RunIdentity for Files and every prompt request. Weak keys
+    // release the captured prose with the run, including failure and cancellation.
+    const prompts = new WeakMap();
+    return defineExtension({ id: homeContract.id, version: "1.0.0" })
+        .config(config)
+        .state({ version: 1, migrations: {}, collections })
+        .define({
+        catalog: catalog([
+            {
+                id: "home",
+                title: "Home Computer",
+                category: "Settings",
+                description: "Choose the default Computer",
+                projections: {
+                    help: { order: 5 },
+                    palette: { order: 5 },
+                    slash: {
+                        aliases: ["home"],
+                        order: 5,
+                        arguments: {
+                            hint: "<name>",
+                            text: { field: "name", arguments: {} },
+                        },
+                    },
+                },
+            },
+        ]),
+        projection: {
+            schema: Schema.NullOr(Home),
+            read: (ctx) => Option.some(Option.getOrNull(ctx.state.choice.peek("default"))),
+        },
+        files: (ctx, run) => {
+            const computers = [...options.computers.read(run)];
+            const choice = ctx.state.update((state) => {
+                const recorded = Option.getOrNull(state.choice.get("default"));
+                if (recorded !== null)
+                    return recorded;
+                const sole = computers.length === 1 ? computers[0] : undefined;
+                if (sole === undefined)
+                    return null;
+                const adopted = { attachmentId: sole.attachmentId };
+                state.choice.put(adopted);
+                return adopted;
+            });
+            const selected = computers.find((computer) => computer.attachmentId === choice?.attachmentId);
+            const status = selected !== undefined
+                ? `Home: ${selected.name}.`
+                : choice?.attachmentId == null
+                    ? "No Home selected. Ask a person to choose /home <name>."
+                    : "Home's default Computer is detached. Ask a person to choose /home <name>; there is no fallback.";
+            const mounts = computers
+                .map((computer) => `computer://${encodeURIComponent(computer.name)}/`)
+                .join(", ");
+            const prompt = `${ctx.config.guide}\n${status}\nCaptured mounts: ${mounts || "none"}.`;
+            prompts.set(run, prompt.slice(0, ctx.config.promptLimit));
+            if (selected === undefined)
+                return null;
+            return Knapsack.files({
+                port: homeFilesRouting(new Map(computers.map(({ name, port }) => [name, port])), selected.port),
+                pathInstructions: "Bare paths and computer://home/ select Home. computer://<name>/ selects another captured attachment. apply_patch uses Home only.",
+            }).tools;
+        },
+        prompt: (_ctx, run) => [
+            {
+                name: "home",
+                text: prompts.get(run) ??
+                    "Home file tools were not captured. Ask the person to check Home's Files grant.",
+            },
+        ],
+        commands: {
+            specs: homeContract.commands,
+            handlers: (ctx) => ({
+                home: ({ input, sessionId }) => Effect.gen(function* () {
+                    const computers = options.computers.read({ sessionId });
+                    if (input.name === undefined) {
+                        if (computers.length === 0)
+                            return done({
+                                type: "info",
+                                message: "No Computers attached. Attach one before choosing Home.",
+                            });
+                        return ask({
+                            type: "choice",
+                            message: "Choose this Agent's Home Computer",
+                            options: computers.map(({ name }) => ({
+                                value: name,
+                                label: name,
+                            })),
+                        }, {}, "name");
+                    }
+                    const selected = computers.find(({ name }) => name === input.name);
+                    if (selected === undefined)
+                        return yield* Effect.fail(new ExtensionCommandError({
+                            reason: "invalid",
+                            message: `Computer is not attached: ${input.name}`,
+                        }));
+                    yield* ctx.state.choice.put({
+                        attachmentId: selected.attachmentId,
+                    });
+                    yield* ctx.observe(sessionId);
+                    return done({
+                        type: "success",
+                        message: `Home: ${selected.name}`,
+                    });
+                }),
+                seed: ({ input }) => Effect.gen(function* () {
+                    if (Option.isSome(yield* ctx.state.choice.get("default")))
+                        return { seeded: false };
+                    yield* ctx.state.choice.put(input);
+                    return { seeded: true };
+                }),
+            }),
+        },
+    });
+}

package/dist/home/routing.d.ts

@@ -0,0 +1,3 @@
+import type { FilesPort } from "@fungi.computer/knapsack";
+/** URI names select captured ports; they cannot create or widen authority. */
+export declare function homeFilesRouting(connections: ReadonlyMap<string, FilesPort>, home: FilesPort): FilesPort;

package/dist/home/routing.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+const computerLocator = z
+    .url({ protocol: /^computer$/ })
+    .transform((value) => new URL(value))
+    .refine((value) => !value.username &&
+    !value.password &&
+    !value.port &&
+    !value.search &&
+    !value.hash, "Computer file locators cannot contain credentials, ports, queries or fragments");
+/** URI names select captured ports; they cannot create or widen authority. */
+export function homeFilesRouting(connections, home) {
+    function resolve(locator) {
+        const explicit = /^[A-Za-z][A-Za-z0-9+.-]*:/.test(locator);
+        const uri = explicit ? computerLocator.parse(locator) : null;
+        const mount = uri === null ? "home" : decodeURIComponent(uri.hostname);
+        const port = mount === "home" ? home : connections.get(mount);
+        if (port === undefined)
+            throw new Error(`Files connection unavailable: ${mount}`);
+        // A URI's leading slash separates the mount from its root-relative path.
+        // The selected port still owns containment and its filesystem root.
+        const path = uri === null ? locator : decodeURIComponent(uri.pathname.slice(1)) || ".";
+        const locate = (resultPath) => {
+            if (uri === null)
+                return resultPath;
+            const result = new URL(uri);
+            result.pathname = resultPath.split("/").map(encodeURIComponent).join("/");
+            return result.href;
+        };
+        return { port, path, locate };
+    }
+    const routing = {
+        read: async (input, context) => {
+            const { port, path } = resolve(input.path);
+            const result = await port.read({ ...input, path }, context);
+            return { ...result, path: input.path };
+        },
+        list: async (input, context) => {
+            const { port, path, locate } = resolve(input.path);
+            const result = await port.list({ ...input, path }, context);
+            return {
+                ...result,
+                path: input.path,
+                entries: result.entries.map((entry) => ({
+                    ...entry,
+                    path: locate(entry.path),
+                })),
+            };
+        },
+        glob: async (input, context) => {
+            const { port, path, locate } = resolve(input.path);
+            const result = await port.glob({ ...input, path }, context);
+            return {
+                ...result,
+                path: input.path,
+                matches: result.matches.map(locate),
+            };
+        },
+        grep: async (input, context) => {
+            const { port, path, locate } = resolve(input.path);
+            const result = await port.grep({ ...input, path }, context);
+            return {
+                ...result,
+                path: input.path,
+                matches: result.matches.map((match) => ({
+                    ...match,
+                    path: locate(match.path),
+                })),
+            };
+        },
+        replace: async (input, context) => {
+            const { port, path } = resolve(input.path);
+            const result = await port.replace({ ...input, path }, context);
+            return { ...result, path: input.path };
+        },
+    };
+    // Patches use the selected Home's native engine and jail. URI routing does
+    // not introduce a second patch parser.
+    const patch = home.patch?.bind(home);
+    return patch === undefined ? routing : { ...routing, patch };
+}

package/dist/internal/catalog.d.ts

@@ -0,0 +1,20 @@
+import type { WhistleCatalogStepV1, WhistleCatalogV1 } from "@fungi.computer/whistle/catalog";
+import type { WhistleJsonObject, WhistleNotice, WhistlePrompt } from "@fungi.computer/whistle";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { type Json } from "@fungi.computer/shiitake/extensions";
+/**
+ * The encoded reply of an extension's human command: one `whistle.catalog/v1`
+ * step. Clients parse it again with Whistle's own step parser.
+ */
+export declare const CatalogStep: Schema.declare<WhistleCatalogStepV1, WhistleCatalogStepV1>;
+/** Finish a human command with one closing notice. */
+export declare function done(notice: WhistleNotice): WhistleCatalogStepV1;
+/** Finish without acting on the human's input, so a composer keeps their draft. */
+export declare function declined(notice: WhistleNotice): WhistleCatalogStepV1;
+/** Ask one question; the answer fills `answer` of the next call's arguments. */
+export declare function ask(prompt: WhistlePrompt, next: WhistleJsonObject, answer: string): WhistleCatalogStepV1;
+/** A fresh request id for a flow that starts without one. */
+export declare const freshRequestId: Effect.Effect<string, never, never>;
+/** Declare an extension's advertised catalog with Whistle's own types. */
+export declare function catalog(commands: WhistleCatalogV1["commands"]): Json;

package/dist/internal/catalog.js

@@ -0,0 +1,33 @@
+import { WhistleCatalogStepSchema } from "@fungi.computer/whistle/catalog";
+import { nanoid } from "@fungi.computer/cairn";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { parseExtensionJson, } from "@fungi.computer/shiitake/extensions";
+/**
+ * The encoded reply of an extension's human command: one `whistle.catalog/v1`
+ * step. Clients parse it again with Whistle's own step parser.
+ */
+export const CatalogStep = Schema.declare((input) => WhistleCatalogStepSchema.safeParse(input).success, {
+    representation: {
+        id: "@fungi.computer/whistle/catalog-step/v1",
+        payload: null,
+    },
+});
+/** Finish a human command with one closing notice. */
+export function done(notice) {
+    return { type: "done", notice };
+}
+/** Finish without acting on the human's input, so a composer keeps their draft. */
+export function declined(notice) {
+    return { type: "done", notice, result: { cancelled: true } };
+}
+/** Ask one question; the answer fills `answer` of the next call's arguments. */
+export function ask(prompt, next, answer) {
+    return { type: "prompt", prompt, next: { arguments: next, answer } };
+}
+/** A fresh request id for a flow that starts without one. */
+export const freshRequestId = Effect.sync(() => nanoid());
+/** Declare an extension's advertised catalog with Whistle's own types. */
+export function catalog(commands) {
+    return parseExtensionJson(JSON.stringify({ protocol: "whistle.catalog/v1", commands }));
+}

package/dist/internal/cron.d.ts

@@ -0,0 +1,5 @@
+import { nextOccurrence as coreNextOccurrence } from "@fungi.computer/almanac";
+import { ExtensionCommandError } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+/** The first occurrence strictly after `after`; missed occurrences coalesce. */
+export declare function nextOccurrence(cadence: Parameters<typeof coreNextOccurrence>[0], after: number): Effect.Effect<number, ExtensionCommandError>;

package/dist/internal/cron.js

@@ -0,0 +1,14 @@
+import { nextOccurrence as coreNextOccurrence } from "@fungi.computer/almanac";
+import { ExtensionCommandError } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+/** The first occurrence strictly after `after`; missed occurrences coalesce. */
+export function nextOccurrence(cadence, after) {
+    const next = coreNextOccurrence(cadence, after);
+    return Result.isFailure(next)
+        ? Effect.fail(new ExtensionCommandError({
+            reason: "invalid",
+            message: next.failure.message,
+        }))
+        : Effect.succeed(next.success);
+}

package/dist/internal/history.d.ts

@@ -0,0 +1,29 @@
+import * as Schema from "effect/Schema";
+/** Producer state: committed event identity survives reconnection and trimming. */
+export declare function historySchema<E, EI>(event: Schema.Codec<E, EI>): Schema.Struct<{
+    readonly nextSequence: Schema.Int;
+    readonly omitted: Schema.Int;
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly sequence: Schema.Int;
+        readonly at: Schema.Int;
+        readonly commandId: Schema.NullOr<Schema.String>;
+        readonly event: Schema.Codec<E, EI, never, never>;
+    }>>;
+}>;
+/** The extension's own persisted history, not a core cursor. */
+export type History<E> = Readonly<{
+    nextSequence: number;
+    omitted: number;
+    events: readonly Readonly<{
+        id: string;
+        sequence: number;
+        at: number;
+        commandId: string | null;
+        event: E;
+    }>[];
+}>;
+/** A new producer counter; callers persist it alongside their Session state. */
+export declare function emptyHistory<E>(): History<E>;
+/** Append once inside the owner's state transaction; retention never rejects work. */
+export declare function appendHistory<E>(previous: History<E>, event: E, commandId: string | null, at: number): History<E>;

package/dist/internal/history.js

@@ -0,0 +1,41 @@
+import * as Schema from "effect/Schema";
+/** Producer state: committed event identity survives reconnection and trimming. */
+export function historySchema(event) {
+    return Schema.Struct({
+        nextSequence: Schema.Int.check(Schema.isGreaterThan(0)),
+        omitted: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        events: Schema.Array(Schema.Struct({
+            id: Schema.String,
+            sequence: Schema.Int,
+            at: Schema.Int,
+            commandId: Schema.NullOr(Schema.String),
+            event,
+        })),
+    });
+}
+/** A new producer counter; callers persist it alongside their Session state. */
+export function emptyHistory() {
+    return { nextSequence: 1, omitted: 0, events: [] };
+}
+const encoder = new TextEncoder();
+/** Append once inside the owner's state transaction; retention never rejects work. */
+export function appendHistory(previous, event, commandId, at) {
+    const sequence = previous.nextSequence;
+    const events = [
+        ...previous.events,
+        { id: String(sequence), sequence, at, commandId, event },
+    ];
+    const history = {
+        nextSequence: sequence + 1,
+        omitted: previous.omitted,
+        events,
+    };
+    while (events.length > 32 ||
+        encoder.encode(JSON.stringify(history)).length > 32 * 1024) {
+        if (events.length === 0)
+            break;
+        events.shift();
+        history.omitted += 1;
+    }
+    return history;
+}

package/dist/loop/client.d.ts

@@ -0,0 +1,10 @@
+import { type ClientContributionV1 } from "@fungi.computer/shiitake/client-entry";
+/** Loop supplies its own absolute due copy and advertised stop intent. */
+declare const _default: Readonly<{
+    protocol: "shiitake.client/v1";
+    id: import("@fungi.computer/shiitake/extensions").ExtensionId;
+    correlatedPrompts?: "note";
+    attach?: (context: import("@fungi.computer/shiitake/client-entry").ClientExtensionContextV1) => import("effect/Effect").Effect<void, Error, import("effect/Scope").Scope>;
+    contribute?: (slot: import("@fungi.computer/shiitake").ExtensionSlotV0 | undefined) => ClientContributionV1;
+}>;
+export default _default;

package/dist/loop/client.js

@@ -0,0 +1,89 @@
+import { defineClientEntry, } from "@fungi.computer/shiitake/client-entry";
+import { loopContract } from "./contract.js";
+const tone = (loop) => loop.state === "failed"
+    ? "error"
+    : loop.state === "active"
+        ? "running"
+        : loop.state === "paused"
+            ? "muted"
+            : "settled";
+const due = (at) => new Intl.DateTimeFormat(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    timeZoneName: "short",
+}).format(at);
+/** Loop supplies its own absolute due copy and advertised stop intent. */
+export default defineClientEntry(loopContract, {
+    contribute: (view) => {
+        if (view.status !== "running" || view.value === null)
+            return {
+                chips: [],
+                panel: [],
+                timeline: { cells: [], omitted: 0 },
+                waiting: null,
+            };
+        const { loop, history } = view.value;
+        const waiting = loop !== null && loop.state === "active" && loop.nextDueAt !== null;
+        return {
+            chips: loop === null || (loop.state !== "active" && loop.state !== "paused")
+                ? []
+                : [
+                    {
+                        id: "loop",
+                        order: 2,
+                        row: {
+                            id: "loop",
+                            title: `Loop ${loop.mode === "self_paced" ? "self-paced" : "fixed"}${waiting ? " (waiting)" : ""}`,
+                            tone: tone(loop),
+                        },
+                    },
+                ],
+            panel: loop === null
+                ? []
+                : [
+                    {
+                        id: "loop",
+                        title: `Loop · ${loop.state} · ${loop.mode === "self_paced" ? "self-paced" : `${loop.cron?.expression ?? "fixed"} ${loop.cron?.timeZone ?? ""}`}${loop.nextDueAt === null ? "" : ` · Next ${due(loop.nextDueAt)}`}`,
+                        detail: loop.prompt.slice(0, 1024),
+                        tone: tone(loop),
+                    },
+                    ...(loop.lastError === null
+                        ? []
+                        : [
+                            {
+                                id: "error",
+                                title: loop.lastError.slice(0, 4096),
+                                tone: "error",
+                            },
+                        ]),
+                ],
+            timeline: {
+                omitted: history.omitted,
+                cells: history.events.map(({ event, ...cell }) => ({
+                    ...cell,
+                    rows: [
+                        {
+                            id: "loop",
+                            title: `Loop ${event.state}`,
+                            detail: (event.lastError ?? event.reason ?? event.prompt).slice(0, 1024),
+                            tone: tone(event),
+                        },
+                    ],
+                })),
+            },
+            waiting: waiting
+                ? {
+                    summary: `Waiting until ${due(loop.nextDueAt)}`,
+                    cancel: {
+                        id: "loop",
+                        label: "stop loop",
+                        input: { action: "stop" },
+                    },
+                }
+                : null,
+        };
+    },
+});