@fungi.computer/corral 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Corral (`@fungi.computer/corral`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Corral reports a Shiitake client's current activity in the active Herdr pane. It
+is an optional client extension: the client supplies activity, and Herdr owns
+the pane and its lifecycle.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/corral
+```
+
+The package ships ESM only and depends on `effect` and
+[Shiitake](../shiitake/README.md) at runtime. Its only entrypoint,
+`@fungi.computer/corral`, exports the Shiitake client extension as its default
+export and `attachCorral` for hosts that supply their own activity stream.
+
+The default extension reads `HERDR_ENV`, `HERDR_SOCKET_PATH`, and
+`HERDR_PANE_ID` from its process environment. It attaches only when `HERDR_ENV`
+is `1` and both the socket path and pane ID are set. Outside that environment,
+attachment has no effect.
+
+## Quick start
+
+This illustrative example attaches a stream supplied by the client. Closing the
+Effect scope stops reporting and releases the pane's report:
+
+```ts
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { attachCorral } from "@fungi.computer/corral";
+
+const scope = await Effect.runPromise(Scope.make());
+await Effect.runPromise(
+  attachCorral(Stream.fromIterable([{ state: "idle" }, { state: "working" }]), {
+    environment: {
+      HERDR_ENV: "1",
+      HERDR_SOCKET_PATH: "/path/to/herdr.sock",
+      HERDR_PANE_ID: "pane-id",
+    },
+    onError: (error) => console.error("Herdr report failed", error),
+  }).pipe(Scope.provide(scope)),
+);
+await Effect.runPromise(Scope.close(scope, Exit.void));
+```
+
+The snippet is illustrative: a real client supplies its live activity stream and
+the Herdr values from its managed environment. The integration tests run report
+and release requests against a local socket server in
+[`test/activity.test.ts`](test/activity.test.ts).
+
+## Core concepts
+
+The activity stream contains `idle`, `working`, `blocked`, or `unknown`. Corral
+reports changes from that stream. It does not open another Session watch or read
+a Session database. The client remains responsible for producing activity. The
+default entry borrows an AsyncIterable with an independent sliding latest-value
+subscription per iterator and a detach signal. `attachCorral` accepts an Effect
+stream, including a stream with typed `Error` failures. Source and socket errors
+reach `onError`; closing the scope still releases the pane report. Fungi borrows
+its existing Session observation and command interaction store. An open agent
+question, a pending command question or a browser hand-off reports `blocked`.
+Answering it restores the current activity. An agent question may add its short
+header to the blocked message; question bodies, answer choices, answers and
+credentials are never included in reports.
+
+Herdr derives `done` when an unseen background turn returns to `idle`. It owns
+whether the user has seen that completion. Corral never guesses completion from
+an unavailable observation.
+
+`attachCorral` needs an Effect scope. When that scope closes, Corral cancels its
+reporter, closes any in-flight socket, and releases the current pane report. It
+sends `pane.report_agent` and `pane.release_agent` over Herdr's API socket with
+the `fungi:agent:v1` source and `fungi` agent label. A monotone timestamp
+sequence orders reports across attachments and process restarts.
+
+## API reference
+
+See the generated [Corral API reference](docs/api/README.md). The default export
+is an attach-only `shiitake.client/v1` entry. `attachCorral` is the lower-level
+integration for hosts that supply an activity stream directly.
+
+## Examples and checks
+
+The activity tests cover environment gating, activity changes, cleanup on scope
+close, and report failure handling. Run them with:
+
+```sh
+pnpm --filter @fungi.computer/corral test
+```
+
+## Limits and errors
+
+Corral is trusted local extension code, not a sandbox. It does not start or stop
+the Herdr service and does not decide what counts as successful work. Report and
+release requests are optional IPC: each is limited to two seconds. Failures are
+passed to `onError`. A reporting failure does not veto client activity or
+terminal restoration. The caller owns any user-facing recovery.
+
+The wire contract follows Herdr's
+[agent integration guide](https://herdr.dev/docs/add-herdr-support/) and its
+[Pi extension](https://github.com/herdrdev/herdr/blob/v0.9.3/src/integration/assets/pi/herdr-agent-state.ts).
+
+## Contribute and license
+
+Corral is MIT licensed. See [`LICENSE`](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { ExtensionId, type ClientActivityV0 } from "@fungi.computer/shiitake/extensions";
+import * as Stream from "effect/Stream";
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+/** Pane environment supplied by the local Herdr host. */
+export type CorralEnvironment = Readonly<{
+    /** Herdr sets this to "1" for managed processes. */
+    HERDR_ENV?: string | undefined;
+    /** Opaque pane identity inherited by the client. */
+    HERDR_PANE_ID?: string | undefined;
+    /** Local API socket (or named pipe on Windows). */
+    HERDR_SOCKET_PATH?: string | undefined;
+}>;
+/** Activity supplied by the client; blocked means a human response is pending. */
+export type CorralActivity = ClientActivityV0;
+/** Attach to borrowed activity; never opens a Session watch or starts Herdr. */
+export declare function attachCorral(activity: Stream.Stream<CorralActivity, Error>, options: Readonly<{
+    environment: CorralEnvironment;
+    onError: (cause: Error) => void;
+}>): Effect.Effect<void, Error, Scope.Scope>;
+/** Ordinary Fungi client extension; disabled outside a Herdr pane. */
+declare const extension: Readonly<{
+    protocol: "shiitake.client/v1";
+    id: ExtensionId;
+    promptPresentation?: "footer";
+    attach?: (context: import("@fungi.computer/shiitake/client-entry").ClientExtensionContextV1) => Effect.Effect<void, Error, Scope.Scope>;
+    contribute?: (slot: import("@fungi.computer/shiitake/extensions").ExtensionSlotV0 | undefined) => import("@fungi.computer/shiitake/client-entry").ClientContributionV1;
+}>;
+export default extension;

package/dist/index.js

@@ -0,0 +1,106 @@
+import { defineClientEntry } from "@fungi.computer/shiitake/client-entry";
+import process from "node:process";
+import { once } from "node:events";
+import { createConnection } from "node:net";
+import { createInterface } from "node:readline";
+import { ExtensionId, } from "@fungi.computer/shiitake/extensions";
+import * as Stream from "effect/Stream";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+const source = "fungi:agent:v1";
+let reportSequence = Date.now() * 1000;
+const decodeResponse = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Union([
+    Schema.Struct({ id: Schema.String, result: Schema.Unknown }),
+    Schema.Struct({
+        id: Schema.String,
+        error: Schema.Struct({ code: Schema.String, message: Schema.String }),
+    }),
+])));
+function nextSequence() {
+    reportSequence = Math.max(reportSequence + 1, Date.now() * 1000);
+    return reportSequence;
+}
+function request(endpoint, pane, activity) {
+    const state = activity?.state;
+    const seq = nextSequence();
+    const id = `${source}:${String(seq)}`;
+    const params = {
+        pane_id: pane,
+        source,
+        agent: "fungi",
+        seq,
+    };
+    if (state !== undefined)
+        params.state = state;
+    if (state === "blocked")
+        params.message =
+            activity?.header === undefined
+                ? "Waiting for your response"
+                : `Waiting for your response: ${activity.header}`;
+    const body = {
+        id,
+        method: state === undefined ? "pane.release_agent" : "pane.report_agent",
+        params,
+    };
+    return Effect.tryPromise({
+        try: async (signal) => {
+            const socket = createConnection({ path: endpoint, signal });
+            const lines = createInterface({ input: socket, crlfDelay: Infinity });
+            try {
+                const replies = lines[Symbol.asyncIterator]();
+                const [, reply] = await Promise.all([
+                    once(socket, "connect", { signal }).then(() => {
+                        socket.write(`${JSON.stringify(body)}\n`);
+                    }),
+                    replies.next(),
+                ]);
+                if (reply.done)
+                    throw new Error("Herdr closed without a response");
+                const response = decodeResponse(reply.value);
+                if (response.id !== id)
+                    throw new Error("Herdr response ID mismatch");
+                if ("error" in response)
+                    throw new Error(`Herdr report refused: ${response.error.code}`);
+            }
+            finally {
+                lines.close();
+                socket.destroy();
+            }
+        },
+        catch: (cause) => new Error("Herdr report failed", { cause }),
+    }).pipe(Effect.timeout("2 seconds"));
+}
+/** Attach to borrowed activity; never opens a Session watch or starts Herdr. */
+export function attachCorral(activity, options) {
+    const { HERDR_ENV, HERDR_SOCKET_PATH, HERDR_PANE_ID } = options.environment;
+    if (HERDR_ENV !== "1" || !HERDR_SOCKET_PATH || !HERDR_PANE_ID)
+        return Effect.void;
+    const endpoint = process.platform === "win32"
+        ? `\\\\.\\pipe\\${HERDR_SOCKET_PATH}`
+        : HERDR_SOCKET_PATH;
+    const send = (activity) => request(endpoint, HERDR_PANE_ID, activity).pipe(Effect.catch((cause) => Effect.sync(() => {
+        options.onError(cause);
+    })));
+    return Effect.gen(function* () {
+        yield* Effect.acquireRelease(Effect.void, () => send(undefined));
+        yield* activity.pipe(Stream.changesWith((a, b) => a.state === b.state && a.header === b.header), Stream.runForEach(send), Effect.catch((cause) => Effect.sync(() => {
+            options.onError(cause);
+        })), Effect.forkScoped);
+    });
+}
+/** Ordinary Fungi client extension; disabled outside a Herdr pane. */
+const extension = defineClientEntry({
+    id: ExtensionId.make("corral"),
+    commands: {},
+    projection: null,
+}, {
+    attach: ({ activity, onError }) => attachCorral(Stream.fromAsyncIterable(activity, (cause) => new Error("Corral activity delivery failed", { cause })), {
+        environment: {
+            HERDR_ENV: process.env.HERDR_ENV,
+            HERDR_SOCKET_PATH: process.env.HERDR_SOCKET_PATH,
+            HERDR_PANE_ID: process.env.HERDR_PANE_ID,
+        },
+        onError,
+    }),
+});
+export default extension;

package/docs/api/README.md

@@ -0,0 +1,68 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/corral**
+
+---
+
+# @fungi.computer/corral
+
+## Type Aliases
+
+### CorralEnvironment
+
+```ts
+type CorralEnvironment = Readonly<{
+  HERDR_ENV?: string;
+  HERDR_PANE_ID?: string;
+  HERDR_SOCKET_PATH?: string;
+}>;
+```
+
+Pane environment supplied by the local Herdr host.
+
+---
+
+### CorralActivity
+
+```ts
+type CorralActivity = ClientActivityV0;
+```
+
+Activity supplied by the client; blocked means a human response is pending.
+
+## Variables
+
+### default
+
+```ts
+const default: Readonly<{
+  protocol: "shiitake.client/v1";
+  id: string & Brand<"ExtensionId">;
+  promptPresentation?: "footer";
+  attach?: (context) => Effect<void, Error, Scope>;
+  contribute?: (slot) => object;
+}>;
+```
+
+Ordinary Fungi client extension; disabled outside a Herdr pane.
+
+## Functions
+
+### attachCorral()
+
+```ts
+function attachCorral(activity, options): Effect<void, Error, Scope>;
+```
+
+Attach to borrowed activity; never opens a Session watch or starts Herdr.
+
+#### Parameters
+
+| Parameter  | Type                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `activity` | `Stream`\<`Readonly`\<\{ `state`: `ClientActivityStateV0`; `header?`: `string`; \}\>, `Error`\>               |
+| `options`  | `Readonly`\<\{ `environment`: [`CorralEnvironment`](#corralenvironment); `onError`: (`cause`) => `void`; \}\> |
+
+#### Returns
+
+`Effect`\<`void`, `Error`, `Scope`\>

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@fungi.computer/corral",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Optional Herdr activity reporting for Shiitake clients",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "effect": "4.0.2",
+    "@fungi.computer/shiitake": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "license": "MIT",
+  "author": "Levi <levi@technomancy.dev>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/corral.git"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src test --max-warnings=0",
+    "test": "vitest run",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "mkdir -p ../../.botanical/corral-pack && pnpm pack --pack-destination ../../.botanical/corral-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({ attachCorral }) => { if (typeof attachCorral !== 'function') process.exit(1); })\"",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }