@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/model-preference.md

@@ -0,0 +1,151 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / model-preference
+
+# model-preference
+
+## Variables
+
+### ModelPreferenceSchema
+
+```ts
+const ModelPreferenceSchema: Struct<{
+  providerId: String;
+  modelId: String;
+  reasoning: optional<
+    Literals<readonly ["minimal", "low", "medium", "high", "xhigh", "max"]>
+  >;
+}>;
+```
+
+Secret-free request to the host's maintained model catalogue.
+
+---
+
+### parseModelPreference
+
+```ts
+const parseModelPreference: (
+  input,
+  options?,
+) => {
+  providerId: string;
+  modelId: string;
+  reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+} | null;
+```
+
+Decode the bounded client preference; availability remains model-owner policy.
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `input`    | `unknown`      |
+| `options?` | `ParseOptions` |
+
+#### Returns
+
+\| \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"minimal"` \|
+`"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`; \} \| `null`
+
+---
+
+### parseModelPreferenceJson
+
+```ts
+const parseModelPreferenceJson: (
+  input,
+  options?,
+) => {
+  providerId: string;
+  modelId: string;
+  reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+} | null;
+```
+
+Decode the serialized preference with the same maintained schema.
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `input`    | `unknown`      |
+| `options?` | `ParseOptions` |
+
+#### Returns
+
+\| \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"minimal"` \|
+`"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`; \} \| `null`
+
+---
+
+### modelPreferenceJsonSchema
+
+```ts
+const modelPreferenceJsonSchema: JsonSchema;
+```
+
+JSON Schema generated from Shiitake's maintained model preference schema.
+
+## Functions
+
+### parseModelAddress()
+
+```ts
+function parseModelAddress(input): object;
+```
+
+Parse the footer's provider/model spelling; model ids may contain slashes.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `input`   | `unknown` |
+
+#### Returns
+
+`object`
+
+| Name         | Type                                                                     | Default value |
+| ------------ | ------------------------------------------------------------------------ | ------------- |
+| `providerId` | `string`                                                                 | `identifier`  |
+| `modelId`    | `string`                                                                 | `identifier`  |
+| `reasoning?` | `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | -             |
+
+---
+
+### resolveModelPreference()
+
+```ts
+function resolveModelPreference(layers): {
+  providerId: string;
+  modelId: string;
+  reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+} | null;
+```
+
+Resolve host-owned defaults for a future run. Hosts supply offered, logged-in
+availability; an explicit choice never silently falls through on auth failure.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `layers`  | `Readonly`\<\{ `session?`: [`ModelPreference`](index.md#modelpreference) \| `null`; `agent?`: [`ModelPreference`](index.md#modelpreference) \| `null`; `manual?`: [`ModelPreference`](index.md#modelpreference) \| `null`; `team?`: [`ModelPreference`](index.md#modelpreference) \| `null`; `available?`: [`ModelPreference`](index.md#modelpreference) \| `null`; \}\> |
+
+#### Returns
+
+\| \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"minimal"` \|
+`"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`; \} \| `null`
+
+## References
+
+### ModelPreference
+
+Re-exports [ModelPreference](index.md#modelpreference)

package/docs/api/node.md

@@ -0,0 +1,142 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / node
+
+# node
+
+## Type Aliases
+
+### NodeRuntimeHost
+
+```ts
+type NodeRuntimeHost = Readonly<{
+  runtime: RuntimeHost;
+  scheduleWake: (at) => void;
+  close: () => Promise<void>;
+}>;
+```
+
+The event-loop runtime host one Node process gives one durable Agent.
+
+---
+
+### NodeStoreLease
+
+```ts
+type NodeStoreLease = Readonly<{
+  release: () => void;
+}>;
+```
+
+An exclusive, process-held claim on one store file.
+
+---
+
+### NodeShiitakeOptions
+
+```ts
+type NodeShiitakeOptions = Omit<ShiitakeOptions, "store" | "runtime"> &
+  Readonly<{
+    path: string;
+    onRuntimeFailure?: (cause) => void;
+  }>;
+```
+
+Everything a Node host supplies except the store and runtime it owns.
+
+---
+
+### NodeShiitake
+
+```ts
+type NodeShiitake = Readonly<{
+  agent: ShiitakeOwnerAgent;
+  routes: Hono<ShiitakeHttpEnv>;
+  close: () => Promise<void>;
+}>;
+```
+
+One durable Agent in a SQLite file, owned by this Node process.
+
+## Functions
+
+### nodeRuntimeHost()
+
+```ts
+function nodeRuntimeHost(observeFailure): NodeRuntimeHost;
+```
+
+The Node event loop as Shiitake's runtime host: one reconciliation at a time,
+re-run when woken during a pass, and a timer for the earliest due retry. It has
+no queue policy; Watchdog owns execution and retries. `observeFailure` sees a
+failed pass, which is retried after five seconds; if it throws, the throw is
+logged and the retry still happens.
+
+#### Parameters
+
+| Parameter        | Type                |
+| ---------------- | ------------------- |
+| `observeFailure` | (`cause`) => `void` |
+
+#### Returns
+
+[`NodeRuntimeHost`](#noderuntimehost)
+
+---
+
+### acquireNodeStoreLease()
+
+```ts
+function acquireNodeStoreLease(sidecarPath): NodeStoreLease;
+```
+
+Claim one store for this process: an exclusive transaction held open on a
+sidecar file, so a second owner of the same store is refused at once and the
+claim ends with the process, never with a missed heartbeat.
+
+#### Parameters
+
+| Parameter     | Type     |
+| ------------- | -------- |
+| `sidecarPath` | `string` |
+
+#### Returns
+
+[`NodeStoreLease`](#nodestorelease)
+
+---
+
+### openNodeShiitake()
+
+```ts
+function openNodeShiitake(options): Promise<
+  Readonly<{
+    agent: ShiitakeOwnerAgent;
+    routes: Hono<ShiitakeHttpEnv>;
+    close: () => Promise<void>;
+  }>
+>;
+```
+
+Open one durable Agent in a SQLite file on disk. The process holds an exclusive
+lease on the store until `close`, so a second opener is refused. The store and
+its lease file are private to this user (0600), and a store reached through a
+symbolic link or with a second hard link is refused. Accepted work survives a
+restart: reopening the file resumes it.
+
+#### Parameters
+
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `options` | [`NodeShiitakeOptions`](#nodeshiitakeoptions) |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `agent`:
+[`ShiitakeOwnerAgent`](index.md#shiitakeowneragent); `routes`:
+`Hono`\<[`ShiitakeHttpEnv`](http.md#shiitakehttpenv)\>; `close`: () =>
+`Promise`\<`void`\>; \}\>\>

package/docs/api/testing.md

@@ -0,0 +1,250 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / testing
+
+# testing
+
+## Classes
+
+### ScriptedToolCall
+
+One scripted model tool call; the scripted sandbox runs exactly this call.
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ScriptedToolCall(path, input): ScriptedToolCall;
+```
+
+###### Parameters
+
+| Parameter | Type                         | Description                                                             |
+| --------- | ---------------------------- | ----------------------------------------------------------------------- |
+| `path`    | `string`                     | `<alias>.<operation>` as the model would call it, e.g. `bookmarks.add`. |
+| `input`   | [`Json`](extensions.md#json) | -                                                                       |
+
+###### Returns
+
+[`ScriptedToolCall`](#scriptedtoolcall)
+
+#### Properties
+
+##### path
+
+```ts
+readonly path: string;
+```
+
+`<alias>.<operation>` as the model would call it, e.g. `bookmarks.add`.
+
+##### input
+
+```ts
+readonly input: Json;
+```
+
+## Type Aliases
+
+### ScriptStep
+
+```ts
+type ScriptStep = string | ScriptedToolCall | FauxResponseStep;
+```
+
+One model turn in a test script: a reply, a tool call, or a faux step.
+
+---
+
+### MemoryHostOptions
+
+```ts
+type MemoryHostOptions = Partial<
+  Omit<ShiitakeOptions, "store" | "runtime" | "extensions">
+> &
+  Readonly<{
+    owner?: SqliteOwner;
+    extensions?: ExtensionRosterV0 | readonly RosteredExtensionV0[];
+    script?: readonly ScriptStep[];
+  }>;
+```
+
+Optional canonical Agent inputs and a borrowed owner; defaults are in-memory.
+
+---
+
+### MemoryHost
+
+```ts
+type MemoryHost = Readonly<{
+  agent: ShiitakeOwnerAgent;
+  reconcile: () => Promise<void>;
+  settle: (sessionId, maxTicks?) => Promise<SessionSnapshot>;
+  close: () => Promise<void>;
+}>;
+```
+
+Explicitly driven in-process host for trusted tests and runnable examples.
+
+## Functions
+
+### fauxModelSource()
+
+```ts
+function fauxModelSource(replies): ModelSource;
+```
+
+A deterministic model source for trusted tests; no provider account or I/O.
+
+#### Parameters
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `replies` | readonly `FauxResponseStep`[] |
+
+#### Returns
+
+[`ModelSource`](index.md#modelsource)
+
+---
+
+### callTool()
+
+```ts
+function callTool(path, input?): ScriptedToolCall;
+```
+
+Script one model turn that calls an operation with this input.
+
+#### Parameters
+
+| Parameter | Type                         |
+| --------- | ---------------------------- |
+| `path`    | `string`                     |
+| `input`   | [`Json`](extensions.md#json) |
+
+#### Returns
+
+[`ScriptedToolCall`](#scriptedtoolcall)
+
+---
+
+### echoSystemPrompt()
+
+```ts
+function echoSystemPrompt(): FauxResponseStep;
+```
+
+Script one model turn that replies with the system prompt it received.
+
+#### Returns
+
+`FauxResponseStep`
+
+---
+
+### memoryHost()
+
+```ts
+function memoryHost(options?): Promise<Readonly<{
+  agent: ShiitakeOwnerAgent;
+  reconcile: () => Promise<void>;
+  settle: (sessionId, maxTicks?) => Promise<Readonly<{
+     sessionId: string;
+     cursor: string | null;
+     hasMore: boolean;
+     oldestCursor?: string | null;
+     messages: readonly Readonly<{
+        meta?: ... | ...;
+        origin?: ... | ...;
+        id: string;
+        sequence: number;
+        commandId: ... | ...;
+        value: Message;
+     }>[];
+     terminals: readonly Readonly<{
+        commandId: string;
+        outcome: ... | ... | ... | ...;
+        sequence: number;
+        diagnostic: ... | ...;
+        meta?: ... | ...;
+     }>[];
+     compactions?: readonly Readonly<{
+        id: ...;
+        sequence: ...;
+        at: ...;
+        tokensBefore: ...;
+        tokensAfter: ...;
+        trigger: ...;
+     }>[];
+     compactionNotices?: readonly Readonly<{
+        id: ...;
+        sequence: ...;
+        at: ...;
+        trigger: ...;
+        result: ...;
+        diagnostic: ...;
+     }>[];
+     sandboxFailures?: readonly object[];
+     pending: SessionPendingPrompts;
+     activity: SessionActivity;
+     progress:   | Readonly<{
+        messageId: string;
+        revision: number;
+        text: string;
+        thinking: string;
+        textTruncated: boolean;
+        thinkingTruncated: boolean;
+      }>
+        | null;
+     extensions: SessionExtensionSlots;
+     attention: readonly object[];
+     context?: Readonly<{
+        tokens: number;
+        window: ... | ...;
+     }>;
+  }>>;
+  close: () => Promise<void>;
+}>>;
+```
+
+Compose the real Shiitake runtime over an optional borrowed SQLite owner. Call
+reconcile/settle explicitly after acceptance. Defaults use a faux model and
+rejecting sandbox; custom callbacks are NOT isolation and retain host
+privileges. No submitted JavaScript is evaluated by this helper.
+
+#### Parameters
+
+| Parameter | Type                                      |
+| --------- | ----------------------------------------- |
+| `options` | [`MemoryHostOptions`](#memoryhostoptions) |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `agent`:
+[`ShiitakeOwnerAgent`](index.md#shiitakeowneragent); `reconcile`: () =>
+`Promise`\<`void`\>; `settle`: (`sessionId`, `maxTicks?`) =>
+`Promise`\<`Readonly`\<\{ `sessionId`: `string`; `cursor`: `string` \| `null`;
+`hasMore`: `boolean`; `oldestCursor?`: `string` \| `null`; `messages`: readonly
+`Readonly`\<\{ `meta?`: ... \| ...; `origin?`: ... \| ...; `id`: `string`;
+`sequence`: `number`; `commandId`: ... \| ...; `value`: `Message`; \}\>[];
+`terminals`: readonly `Readonly`\<\{ `commandId`: `string`; `outcome`: ... \|
+... \| ... \| ...; `sequence`: `number`; `diagnostic`: ... \| ...; `meta?`: ...
+\| ...; \}\>[]; `compactions?`: readonly `Readonly`\<\{ `id`: ...; `sequence`:
+...; `at`: ...; `tokensBefore`: ...; `tokensAfter`: ...; `trigger`: ...; \}\>[];
+`compactionNotices?`: readonly `Readonly`\<\{ `id`: ...; `sequence`: ...; `at`:
+...; `trigger`: ...; `result`: ...; `diagnostic`: ...; \}\>[];
+`sandboxFailures?`: readonly `object`[]; `pending`:
+[`SessionPendingPrompts`](client.md#sessionpendingprompts); `activity`:
+[`SessionActivity`](client.md#sessionactivity); `progress`: \| `Readonly`\<\{
+`messageId`: `string`; `revision`: `number`; `text`: `string`; `thinking`:
+`string`; `textTruncated`: `boolean`; `thinkingTruncated`: `boolean`; \}\> \|
+`null`; `extensions`:
+[`SessionExtensionSlots`](client.md#sessionextensionslots); `attention`:
+readonly `object`[]; `context?`: `Readonly`\<\{ `tokens`: `number`; `window`:
+... \| ...; \}\>; \}\>\>; `close`: () => `Promise`\<`void`\>; \}\>\>

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "@fungi.computer/shiitake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Effect-native durable Session acceptance and bounded run orchestration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "import": "./dist/effect.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./agent-control": {
+      "types": "./dist/agent-control.d.ts",
+      "import": "./dist/agent-control.js"
+    },
+    "./model-preference": {
+      "types": "./dist/model-preference.d.ts",
+      "import": "./dist/model-preference.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions.d.ts",
+      "import": "./dist/extensions.js"
+    },
+    "./hosted": {
+      "types": "./dist/hosted.d.ts",
+      "import": "./dist/hosted.js"
+    },
+    "./client-entry": {
+      "types": "./dist/client-entry.d.ts",
+      "import": "./dist/client-entry.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./agar-extension": {
+      "types": "./dist/agar-extension.d.ts",
+      "import": "./dist/agar-extension.js"
+    },
+    "./fleet": {
+      "types": "./dist/fleet.d.ts",
+      "import": "./dist/fleet.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "@fungi.computer/bird-dog": "0.0.1",
+    "@fungi.computer/cairn": "0.0.1",
+    "@fungi.computer/knapsack": "0.0.2",
+    "@fungi.computer/mule": "0.0.2",
+    "@fungi.computer/mycelium": "0.0.2",
+    "@fungi.computer/watchdog": "0.0.1",
+    "effect": "4.0.2",
+    "hono": "4.13.5",
+    "zod": "4.4.3",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@fungi.computer/gills": "0.0.1",
+    "@fungi.computer/agar": "0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260828.1",
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11",
+    "@fungi.computer/carrier": "0.0.1",
+    "@astrojs/starlight": "0.42.4"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/shiitake.git"
+  },
+  "scripts": {
+    "lint": "eslint src test examples --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test examples",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "pnpm run test:unit && pnpm run test:merge",
+    "test:unit": "vitest run",
+    "test:merge": "node test/cloudflare-durable-wake.native.mjs && pnpm run test:docs",
+    "test:docs": "node --import tsx --test examples/bookmarks/checks.ts",
+    "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/shiitake-pack && pnpm pack --pack-destination ../../.botanical/shiitake-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({Shiitake}) => { if (!Shiitake) 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"
+  }
 }