API reference

effect

Import

import * as api from "@fungi.computer/shiitake/effect";

Exports

Kind	Export	Description
type alias	ShiitakeEffectHost	Effect-native host composition with addressed mail kept off Session.
type alias	ModelAcquisitionEffect	Effect-native acquired Pi model and finalizer.
type alias	ModelSourceEffect	Effect-native model acquisition owner.
type alias	InstructionSourceEffect	Effect-native instruction snapshot owner.
type alias	ToolSourceEffect	Effect-native Mycelium construction inputs.
type alias	RuntimeHostEffect	Effect-native owner for scheduling the opaque durable reconciler.
type alias	ShiitakeEffectOptions	Validated construction bag for owned Effect composition.
type alias	ShiitakeEffectWatch	Effect-native race-safe watch result.
type alias	ShiitakeEffectCommandHandler	Effect-native addressable Session handle.
type alias	ShiitakeEffectSendOptions	Delivery intent and an optional private retry key for Effect-native sending.
type alias	ShiitakeEffectSession	Effect-native addressable Session handle.
type alias	ShiitakeEffectSessionExtension	Effect-native Session-scope extension commands.
type alias	ShiitakeEffectAgentExtensions	Effect-native Agent-scope extension controls.
type alias	ShiitakeEffectAgent	Effect-native durable harness.
type alias	ShiitakeEffectOwner	The in-process owner of a durable harness. Only the host holds it, so only the host can write a Session’s grants or attach metadata; no HTTP or remote client can.
type alias	StoredSessionSummary	Persisted conversation facts; run status belongs to the Session’s owner.
type alias	StoredSessionSummaryRow	One persisted conversation’s stored facts, or a row that could not be read.
type alias	StoredSessionSummaryPage	One page of stored conversation facts, in stable Session identity order.
function	make()	Construct the canonical Effect-native Shiitake scaffold.
function	openHost()	Open the Effect-native host composition with addressed mail.
function	readSessionSummaries()	Enumerate saved conversations’ stored facts in bounded pages, for readers that hold only the store. Run status is not stored; use the Agent’s `listSessions` for it. An unreadable Session is its own `unavailable` row.

ShiitakeEffectHosttype alias

type ShiitakeEffectHost = Readonly<{
  readSettlement: (
    sessionId,
    commandId,
  ) => Effect.Effect<CommandSettlement | undefined, ShiitakeError>;
  agent: ShiitakeEffectOwner;
  acceptMail: (
    mail,
    meta?,
    reply?,
    stageAcceptedNotice?,
  ) => Effect.Effect<Accepted, ShiitakeError>;
}>;

Effect-native host composition with addressed mail kept off Session.

ModelAcquisitionEffecttype alias

type ModelAcquisitionEffect = Readonly<{
  model: Model<Api>;
  stream?: MuleStreamFunction;
  retryAfterMs?: (message) => number | undefined;
  retryable: (message) => boolean;
  failureReason?: (message) => string | undefined;
  rejection?: (message) => ProviderRejection | undefined;
  providerError?: (message) => string | undefined;
  release: Effect.Effect<void, ShiitakeError>;
}>;

Effect-native acquired Pi model and finalizer.

ModelSourceEffecttype alias

type ModelSourceEffect = Readonly<{
  acquire: (input) => Effect.Effect<ModelAcquisitionEffect, ShiitakeError>;
  describe?: (input) => Effect.Effect<ModelDescription, ShiitakeError>;
}>;

Effect-native model acquisition owner.

InstructionSourceEffecttype alias

type InstructionSourceEffect = Readonly<{
  load: (
    input,
  ) => Effect.Effect<InstructionSnapshot, ShiitakeError, Scope.Scope>;
}>;

Effect-native instruction snapshot owner.

ToolSourceEffecttype alias

type ToolSourceEffect = Readonly<{
  execution?: ExecutionOptions;
  modules: readonly ModuleRegistration[];
  sources: readonly CapabilitySource[];
  sandbox: Sandbox;
  access?: ToolAccess;
}>;

Effect-native Mycelium construction inputs.

RuntimeHostEffecttype alias

type RuntimeHostEffect = Readonly<{
  bind: (input) => Effect.Effect<
    Readonly<{
      commit: <A>(mutation) => Effect.Effect<A, ShiitakeError>;
      requestWake: Effect.Effect<void, ShiitakeError>;
      close: Effect.Effect<void, ShiitakeError>;
    }>,
    ShiitakeError
  >;
}>;

Effect-native owner for scheduling the opaque durable reconciler.

ShiitakeEffectOptionstype alias

type ShiitakeEffectOptions = Readonly<{
  meta?: HostMetaOptions;
  store: SqliteOwner;
  storagePressure?: StoragePressureCheck;
  compaction?: CompactionOptions;
  hostJobs?: Readonly<{
    lane: string;
    open: (runtime) => Readonly<{
      execute: (job) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
    }>;
  }>;
  model: ModelSourceEffect;
  instructions: InstructionSourceEffect;
  tools?: ToolSourceEffect;
  runtime: RuntimeHostEffect;
  extensions: ExtensionRosterV0;
  retry?: RetryPolicy;
  modelStreamIdleTimeoutMs?: number;
}>;

Validated construction bag for owned Effect composition.

ShiitakeEffectWatchtype alias

type ShiitakeEffectWatch = Readonly<{
  snapshot: SessionSnapshot;
  changes: Stream.Stream<SessionFrame, ShiitakeError>;
  close: Effect.Effect<void, ShiitakeError>;
}>;

Effect-native race-safe watch result.

ShiitakeEffectCommandHandlertype alias

type ShiitakeEffectCommandHandler = {
  (input): Effect<
    Readonly<{
      status: "accepted";
      commandId: string;
      sessionId?: string;
    }>,
    ShiitakeError
  >;
  (input): Effect<CancelResult, ShiitakeError>;
  (input): Effect<undefined, ShiitakeError>;
  (input): Effect<
    Readonly<{
      sessionId: string;
    }>,
    ShiitakeError
  >;
  (input): Effect<
    | CancelResult
    | Readonly<{
        sessionId: string;
      }>
    | undefined,
    ShiitakeError
  >;
};

Effect-native addressable Session handle.

Call Signature

(input): Effect<Readonly<{
  status: "accepted";
  commandId: string;
  sessionId?: string;
}>, ShiitakeError>;

Accept one durable prompt command.

Parameters

Parameter	Type
`input`	`\| { delivery: "followUp" \| "steer"; requestId: string; type: "prompt"; text: string; images?: readonly object[]; } \| { type: "compact"; requestId: string; instructions?: string; }`

Returns

Effect<Readonly<{ status: "accepted"; commandId: string; sessionId?: string; }>, ShiitakeError>

Call Signature

(input): Effect<CancelResult, ShiitakeError>;

Cancel one accepted command, or report that it is too late.

Parameters

Parameter	Type
`input`	`{ commandId: string; onlyIfPending?: boolean; type: "cancel"; }`
`input.commandId`	`string`
`input.onlyIfPending?`	`boolean`
`input.type`	`"cancel"`

Returns

Effect<CancelResult, ShiitakeError>

Call Signature

(input): Effect<undefined, ShiitakeError>;

Abort the active run, select a lineage leaf, or record an operator line.

Parameters

Parameter	Type
`input`	`\| { type: "abort"; } \| { type: "branch"; entryId: string; } \| { type: "operator"; requestId: string; author: "operator" \| "party"; text: string; } \| { type: "title"; title: string \| null; }`

Returns

Effect<undefined, ShiitakeError>

Call Signature

(input): Effect<Readonly<{
  sessionId: string;
}>, ShiitakeError>;

Fork one complete entry lineage into a new Session.

Parameters

Parameter	Type
`input`	`{ type: "fork"; entryId: string; }`
`input.type`	`"fork"`
`input.entryId`	`string`

Returns

Effect<Readonly<{ sessionId: string; }>, ShiitakeError>

Call Signature

(input): Effect<
  | CancelResult
  | Readonly<{
  sessionId: string;
}>
| undefined, ShiitakeError>;

Execute an already-decoded command union.

Parameters

Parameter Type

input | { delivery: "followUp" | "steer"; requestId: string; type: "prompt"; text: string; images?: readonly object[]; } | { type: "abort"; } | { commandId: string; onlyIfPending?: boolean; type: "cancel"; } | { type: "branch"; entryId: string; } | { type: "fork"; entryId: string; } | { type: "operator"; requestId: string; author: "operator" | "party"; text: string; } | { type: "compact"; requestId: string; instructions?: string; } | { type: "title"; title: string | null; }

Parameter	Type
`input`	`\| { delivery: "followUp" \| "steer"; requestId: string; type: "prompt"; text: string; images?: readonly object[]; } \| { type: "abort"; } \| { commandId: string; onlyIfPending?: boolean; type: "cancel"; } \| { type: "branch"; entryId: string; } \| { type: "fork"; entryId: string; } \| { type: "operator"; requestId: string; author: "operator" \| "party"; text: string; } \| { type: "compact"; requestId: string; instructions?: string; } \| { type: "title"; title: string \| null; }`

Returns

Effect< | CancelResult | Readonly<{ sessionId: string; }> | undefined, ShiitakeError>

ShiitakeEffectSendOptionstype alias

type ShiitakeEffectSendOptions = Readonly<{
  images?: PromptCommand["images"];
  delivery?: PromptDelivery;
  requestId?: string;
}>;

Delivery intent and an optional private retry key for Effect-native sending.

ShiitakeEffectSessiontype alias

type ShiitakeEffectSession = Readonly<{
  command: ShiitakeEffectCommandHandler;
  withdraw: (requestId) => Effect.Effect<WithdrawResult, ShiitakeError>;
  abort: Effect.Effect<void, ShiitakeError>;
  send: (text, options?) => Effect.Effect<Accepted, ShiitakeError>;
  cancel: (input) => Effect.Effect<CancelResult, ShiitakeError>;
  latestPending: Effect.Effect<SessionPendingPrompt | null, ShiitakeError>;
  extension: (extensionId) => ShiitakeEffectSessionExtension;
  modelPreference: Readonly<{
    read: Effect.Effect<ModelPreference | null, ShiitakeError>;
    set: (preference) => Effect.Effect<void, ShiitakeError>;
  }>;
  read: (input?) => Effect.Effect<SessionSnapshot, ShiitakeError>;
  readSettlement: (
    commandId,
    timeoutMs?,
  ) => Effect.Effect<CommandSettlement | undefined, ShiitakeError>;
  subscribe: (input) => Stream.Stream<SessionFrame, ShiitakeError>;
  watch: (input?) => Effect.Effect<ShiitakeEffectWatch, ShiitakeError>;
}>;

Effect-native addressable Session handle.

ShiitakeEffectSessionExtensiontype alias

type ShiitakeEffectSessionExtension = Readonly<{
  call: (command, input) => Effect.Effect<Json, ShiitakeError>;
}>;

Effect-native Session-scope extension commands.

ShiitakeEffectAgentExtensionstype alias

type ShiitakeEffectAgentExtensions = Readonly<{
  list: Effect.Effect<readonly ExtensionStatusV0[], ShiitakeError>;
  resume: (extensionId) => Effect.Effect<ExtensionStatusV0, ShiitakeError>;
  call: (extensionId, command, input) => Effect.Effect<Json, ShiitakeError>;
}>;

Effect-native Agent-scope extension controls.

ShiitakeEffectAgenttype alias

type ShiitakeEffectAgent = Readonly<{
  createSession: (requestId) => Effect.Effect<string, ShiitakeError>;
  deleteSession: (sessionId) => Effect.Effect<boolean, ShiitakeError>;
  listSessions: (after?) => Effect.Effect<SessionSummaryPage, ShiitakeError>;
  extensions: ShiitakeEffectAgentExtensions;
  session: (sessionId) => ShiitakeEffectSession;
  close: Effect.Effect<void, ShiitakeError>;
}>;

Effect-native durable harness.

ShiitakeEffectOwnertype alias

type ShiitakeEffectOwner = ShiitakeEffectAgent &
  Readonly<{
    prepareConfiguration: (configuration) => Effect.Effect<
      Readonly<{
        commit: Effect.Effect<void, ShiitakeError>;
        discard: Effect.Effect<void>;
      }>,
      ShiitakeError
    >;
    grants: Readonly<{
      deliver: (
        sessionId,
        delivery,
      ) => Effect.Effect<GrantsDeliveryResult, ShiitakeError>;
      read: (sessionId) => Effect.Effect<GrantsDelivery | null, ShiitakeError>;
    }>;
    withMeta: (meta) => ShiitakeEffectAgent;
  }>;

The in-process owner of a durable harness. Only the host holds it, so only the host can write a Session’s grants or attach metadata; no HTTP or remote client can.

StoredSessionSummarytype alias

type StoredSessionSummary = Readonly<{
  createdAt: number;
  updatedAt: number;
  title: string;
}>;

Persisted conversation facts; run status belongs to the Session’s owner.

StoredSessionSummaryRowtype alias

type StoredSessionSummaryRow =
  | (StoredSessionSummary &
      Readonly<{
        kind: "session";
        sessionId: string;
      }>)
  | Readonly<{
      kind: "unavailable";
      sessionId: string;
    }>;

One persisted conversation’s stored facts, or a row that could not be read.

StoredSessionSummaryPagetype alias

type StoredSessionSummaryPage = Readonly<{
  sessions: readonly StoredSessionSummaryRow[];
  next: string | undefined;
}>;

One page of stored conversation facts, in stable Session identity order.

make()function

function make(options): Effect<ShiitakeEffectOwner, ShiitakeError>;

Construct the canonical Effect-native Shiitake scaffold.

Parameters

Parameter	Type
`options`	`ShiitakeEffectOptions`

Returns

Effect<ShiitakeEffectOwner, ShiitakeError>

openHost()function

function openHost(options, mailRoom): Effect<Readonly<{
  readSettlement: (sessionId, commandId) => Effect<
     | Readonly<{
     acceptedSender: string | null;
     terminal: SessionTerminal;
     content: string;
     usage: readonly Pick<AssistantMessage, ... | ... | ...>[];
     toolCalls: number;
   }>
    | undefined, ShiitakeError>;
  agent: ShiitakeEffectOwner;
  acceptMail: (mail, meta?, reply?, stageAcceptedNotice?) => Effect<Readonly<{
     status: "accepted";
     commandId: string;
     sessionId?: string;
  }>, ShiitakeError>;
}>, ShiitakeError>;

Open the Effect-native host composition with addressed mail.

Parameters

Parameter	Type
`options`	`ShiitakeEffectOptions`
`mailRoom`	`BirdDogEffect`

Returns

Effect<Readonly<{ readSettlement: (sessionId, commandId) => Effect< | Readonly<{ acceptedSender: string | null; terminal: SessionTerminal; content: string; usage: readonly Pick<AssistantMessage, … | … | …>[]; toolCalls: number; }> | undefined, ShiitakeError>; agent: ShiitakeEffectOwner; acceptMail: (mail, meta?, reply?, stageAcceptedNotice?) => Effect<Readonly<{ status: "accepted"; commandId: string; sessionId?: string; }>, ShiitakeError>; }>, ShiitakeError>

readSessionSummaries()function

function readSessionSummaries(
  owner,
  after?,
): Effect<
  Readonly<{
    sessions: readonly StoredSessionSummaryRow[];
    next: string | undefined;
  }>,
  ShiitakeError,
  never
>;

Enumerate saved conversations’ stored facts in bounded pages, for readers that hold only the store. Run status is not stored; use the Agent’s listSessions for it. An unreadable Session is its own unavailable row.