@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,81 @@
+import * as Schema from "effect/Schema";
+/** Stable boundary that rejected a Shiitake operation. */
+const ShiitakeErrorBoundarySchema = Schema.Literals([
+    "contract",
+    "extensions",
+    "instructions",
+    "model",
+    "runtime",
+    "store",
+    "tools",
+]);
+/** Safe failure category exposed by both Shiitake facades. */
+const ShiitakeErrorCauseSchema = Schema.Literals([
+    "closed",
+    "conflict",
+    "incompatible",
+    "invalid",
+    "rejected",
+    "unavailable",
+    /** Owner storage is near its budget; new Sessions and prompts wait. */
+    "storage_pressure",
+    /** One model context read is larger than the owner can safely decode. */
+    "context_too_large",
+]);
+const requestIdSchema = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
+/** Canonical serialized Shiitake failure. */
+export const ShiitakeErrorWireSchema = Schema.Struct({
+    _tag: Schema.Literal("ShiitakeError"),
+    boundary: ShiitakeErrorBoundarySchema,
+    cause: ShiitakeErrorCauseSchema,
+    message: Schema.String,
+    requestId: Schema.optionalKey(requestIdSchema),
+});
+/** Sanitized failure from a parsed Shiitake boundary. */
+export class ShiitakeError extends Error {
+    boundary;
+    requestId;
+    /** Stable runtime tag for typed Shiitake failures. */
+    _tag = "ShiitakeError";
+    /** Safe category describing why it was rejected. */
+    cause;
+    /** Original cause retained only for server-side diagnosis. */
+    underlying;
+    /** Construct a sanitized boundary failure. */
+    constructor(
+    /** Boundary that rejected the operation. */
+    boundary, 
+    /** Safe category describing why it was rejected. */
+    category, 
+    /** Human-readable message safe for callers to display. */
+    message, 
+    /** Request identity recoverable when a send may have reached the owner. */
+    requestId, 
+    /**
+     * The original thrown value, kept for server-side diagnosis only. It is
+     * never serialized: the wire encoder copies named fields only.
+     */
+    cause) {
+        super(message);
+        this.boundary = boundary;
+        this.requestId = requestId;
+        this.name = "ShiitakeError";
+        this.cause = category;
+        this.underlying = cause;
+    }
+}
+/** Sanitize one caught host failure for Shiitake's public wire. */
+export function toShiitakeErrorWire(cause) {
+    const failure = cause instanceof ShiitakeError
+        ? cause
+        : new ShiitakeError("runtime", "unavailable", "Shiitake operation failed");
+    const wire = {
+        _tag: failure._tag,
+        boundary: failure.boundary,
+        cause: failure.cause,
+        message: failure.message,
+    };
+    if (failure.requestId !== undefined)
+        Object.assign(wire, { requestId: failure.requestId });
+    return Object.freeze(wire);
+}

package/dist/extension-client.d.ts

@@ -0,0 +1,38 @@
+import type { SessionExtensionSlots, ShiitakeAgent, ShiitakeSession } from "./client.js";
+import type { CommandsV0, ExtensionContractV0, ExtensionSlotV0 } from "./extensions.js";
+/** What one client sees of an extension in a Session observation. */
+export type ExtensionViewV0<P> = Readonly<{
+    status: "unavailable";
+}> | Readonly<{
+    status: "stopped";
+    reason: string;
+}> | Readonly<{
+    status: "running";
+    value: P | null;
+}>;
+/** Command names of one scope, typed by the shared contract. */
+export type ScopedCommandsV0<C extends CommandsV0, S extends "session" | "agent"> = {
+    [K in keyof C & string]: C[K]["scope"] extends S ? K : never;
+}[keyof C & string];
+/** Typed call surface of one contract's commands in one scope. */
+export type BoundCallV0<C extends CommandsV0, S extends "session" | "agent"> = <K extends ScopedCommandsV0<C, S>>(name: K, input: C[K]["input"]["Type"]) => Promise<C[K]["output"]["Type"]>;
+/** One Session bound to one extension contract. */
+export type BoundSessionExtensionV0<C extends CommandsV0, P> = Readonly<{
+    /** Decode this extension's slot from a snapshot or update frame. */
+    view: (observation: Readonly<{
+        extensions: SessionExtensionSlots;
+    }>) => ExtensionViewV0<P>;
+    /** Encode, call, and decode one Session-scope command. */
+    call: BoundCallV0<C, "session">;
+}>;
+/** One Agent bound to one extension contract. */
+export type BoundAgentExtensionV0<C extends CommandsV0> = Readonly<{
+    /** Encode, call, and decode one Agent-scope command. */
+    call: BoundCallV0<C, "agent">;
+}>;
+/** Decode one observed slot using its owning contract's projection. */
+export declare function viewExtension<C extends CommandsV0, P, PI>(contract: ExtensionContractV0<C, P, PI>, slot: ExtensionSlotV0 | undefined): ExtensionViewV0<P>;
+/** Bind one Session to one extension contract; the contract's schemas decode. */
+export declare function bindSessionExtension<C extends CommandsV0, P, PI>(session: Pick<ShiitakeSession, "extension">, contract: ExtensionContractV0<C, P, PI>): BoundSessionExtensionV0<C, P>;
+/** Bind one Agent to one extension contract's Agent-scope commands. */
+export declare function bindAgentExtension<C extends CommandsV0, P, PI>(agent: Pick<ShiitakeAgent, "extensions">, contract: ExtensionContractV0<C, P, PI>): BoundAgentExtensionV0<C>;

package/dist/extension-client.js

@@ -0,0 +1,56 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "./errors.js";
+import { JsonValueSchema } from "./internal/json-value.js";
+const decodeJson = Schema.decodeUnknownResult(JsonValueSchema);
+function contractFailure(message) {
+    return new ShiitakeError("contract", "invalid", message);
+}
+function typedCall(contract, send) {
+    return async (name, input) => {
+        const spec = Object.hasOwn(contract.commands, name)
+            ? contract.commands[name]
+            : undefined;
+        if (spec === undefined)
+            throw contractFailure("Extension command is unknown");
+        const encoded = Schema.encodeUnknownResult(spec.input)(input).pipe(Result.flatMap(decodeJson));
+        if (encoded._tag === "Failure")
+            throw contractFailure("Extension command input is invalid");
+        const output = Schema.decodeUnknownResult(spec.output)(await send(name, encoded.success));
+        if (output._tag === "Failure")
+            throw contractFailure("Extension output does not match its contract");
+        return output.success;
+    };
+}
+/** Decode one observed slot using its owning contract's projection. */
+export function viewExtension(contract, slot) {
+    if (slot === undefined)
+        return { status: "unavailable" };
+    if (slot.status === "stopped")
+        return { status: "stopped", reason: slot.reason };
+    if (slot.value === null || contract.projection === null)
+        return { status: "running", value: null };
+    const decoded = Schema.decodeUnknownResult(contract.projection.schema)(slot.value);
+    return decoded._tag === "Success"
+        ? { status: "running", value: decoded.success }
+        : {
+            status: "stopped",
+            reason: "Extension projection does not match this client",
+        };
+}
+/** Bind one Session to one extension contract; the contract's schemas decode. */
+export function bindSessionExtension(session, contract) {
+    const address = session.extension(contract.id);
+    return Object.freeze({
+        view: (observation) => viewExtension(contract, Object.hasOwn(observation.extensions, contract.id)
+            ? observation.extensions[contract.id]
+            : undefined),
+        call: typedCall(contract, (command, input) => address.call(command, input)),
+    });
+}
+/** Bind one Agent to one extension contract's Agent-scope commands. */
+export function bindAgentExtension(agent, contract) {
+    return Object.freeze({
+        call: typedCall(contract, (command, input) => agent.extensions.call(contract.id, command, input)),
+    });
+}

package/dist/extension-contract.d.ts

@@ -0,0 +1,73 @@
+import * as Schema from "effect/Schema";
+/** Host extension protocol; client-entry protocol is versioned independently. */
+export type ShiitakeExtensionProtocolV0 = "shiitake.extension/v0";
+/** ASCII extension identity shared by the host definition and its clients. */
+export declare const extensionIdentifier: Schema.String;
+/** SemVer spelling used by host admission. */
+export declare const extensionVersion: Schema.String;
+/** ASCII extension identity shared by the host definition and its clients. */
+export declare const ExtensionId: Schema.brand<Schema.String, "ExtensionId">;
+/** ASCII extension identity shared by the server definition and its clients. */
+export type ExtensionId = Schema.Schema.Type<typeof ExtensionId>;
+/** Core digest of one normalized extension definition. */
+export declare const extensionRevisionSchema: Schema.brand<Schema.String, "ExtensionRevision">;
+/** Core digest of one revision and its sorted granted capabilities. */
+export declare const extensionFingerprintSchema: Schema.brand<Schema.String, "ExtensionFingerprint">;
+/** Closed, versioned, feature-free capability vocabulary. */
+export type ExtensionCapabilityV0 = 
+/** Namespaced schema-typed durable records. */
+"state"
+/** Namespaced durable requests for human attention. */
+ | "attention"
+/** Exactly-once delivery of settled runs from a core-owned cursor. */
+ | "settled"
+/** The one accepted-command door. */
+ | "send"
+/** Durable per-extension wake timers. */
+ | "timers"
+/** Session- and agent-scope commands over the generic call surface. */
+ | "commands"
+/** One encoded slot in every Session snapshot and frame. */
+ | "projection"
+/** A Mycelium module attached to runs this extension participates in. */
+ | "run_tools"
+/** Exclusive Knapsack Files tools captured once per run. */
+ | "files"
+/** Named system-prompt sections, evaluated before each model request. */
+ | "prompt"
+/** The single exclusive compaction handoff slot. */
+ | "compaction_handoff";
+/** Static identity and requested capabilities of one v0 extension. */
+export type ExtensionManifestV0 = Readonly<{
+    protocol: ShiitakeExtensionProtocolV0;
+    id: ExtensionId;
+    /** Semver; bump when behaviour changes outside config and schemas. */
+    version: string;
+    requests: readonly ExtensionCapabilityV0[];
+}>;
+/** One command's scope and its encoded input and output schemas. */
+export type CommandSpecV0<S extends "session" | "agent", I, II, O, OI> = Readonly<{
+    scope: S;
+    input: Schema.Codec<I, II>;
+    output: Schema.Codec<O, OI>;
+}>;
+/** Existential command spec. */
+export type AnyCommandSpecV0 = Readonly<{
+    scope: "session" | "agent";
+    input: Schema.Codec<unknown>;
+    output: Schema.Codec<unknown>;
+}>;
+/** Commands declared by one extension contract. */
+export type CommandsV0 = Readonly<Record<string, AnyCommandSpecV0>>;
+/** The encoded Session projection slot. */
+export type ProjectionSpecV0<P, PI> = Readonly<{
+    schema: Schema.Codec<P, PI>;
+}>;
+/** Shared by the host definition and the client binding: one schema set. */
+export type ExtensionContractV0<C extends CommandsV0, P, PI> = Readonly<{
+    id: ExtensionId;
+    commands: C;
+    projection: ProjectionSpecV0<P, PI> | null;
+}>;
+/** Activity already observed by the client, never an execution authority. */
+export type ClientActivityV0 = "idle" | "working" | "blocked" | "unknown";

package/dist/extension-contract.js

@@ -0,0 +1,11 @@
+import * as Schema from "effect/Schema";
+/** ASCII extension identity shared by the host definition and its clients. */
+export const extensionIdentifier = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128)), Schema.check(Schema.isPattern(/^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$/u)));
+/** SemVer spelling used by host admission. */
+export const extensionVersion = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(64)), Schema.check(Schema.isPattern(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u)));
+/** ASCII extension identity shared by the host definition and its clients. */
+export const ExtensionId = extensionIdentifier.pipe(Schema.brand("ExtensionId"));
+/** Core digest of one normalized extension definition. */
+export const extensionRevisionSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^sha256:[0-9a-f]{64}$/u)), Schema.brand("ExtensionRevision"));
+/** Core digest of one revision and its sorted granted capabilities. */
+export const extensionFingerprintSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^sha256:[0-9a-f]{64}$/u)), Schema.brand("ExtensionFingerprint"));