agent-control

Import

Import

import * as api from "@fungi.computer/shiitake/agent-control";

Exports

Kind	Export	Description
Cclass	AgentArchiveRefused	A host’s refusal to archive or restore an Agent, or to work with one that is archived. It reaches the caller as a failure of the operation it refused.
Cclass	AgentCreateRefused	A host’s refusal of an Agent creating an Agent: the creator asked to give the created Agent more than it holds, the host cannot tell which Agent is creating, or the request id belongs to another creating Agent or Session. It reaches the caller as an agents.create failure.
Ttype alias	AgentControlAnswerInput	Sender-authenticated submission for one child Session’s routed Ask.
Ttype alias	AgentControlEscalateInput	Sender-authenticated escalation of one item a child Session left waiting.
Ttype alias	AgentControlAnswerOutput	Typed outcome of a sender’s answer to a child Ask.
Ttype alias	AgentControlEscalateOutput	Typed outcome of a sender’s escalation of a child’s item.
Ttype alias	ArchiveRefusalReason	One reason in archiveRefusalReasons.
Ttype alias	AgentControlAgent	One existing Agent visible within the caller’s authorized project or Team.
Ttype alias	AgentControlModel	One host-offered model usable as an Agent’s create or setModel choice.
Ttype alias	AgentDelegationInput	One host-authorized delegation, with the caller Session supplied by acquisition.
Ttype alias	AgentRecallInput	Exact authorized destination and caller’s original send identity.
Ttype alias	AgentDelegationInvocation	Host-only identity and admitted command metadata for one delegated send.
Ttype alias	AgentControlDirectory	Host-owned discovery and per-operation access to ordinary Agents.
constconstant	answerOutput	Typed outcome of a sender’s answer to a child Ask.
constconstant	escalateOutput	Typed outcome of a sender’s escalation of a child’s item.
constconstant	archiveRefusalReasons	Why a host refuses an archive or restore: the caller did not create the Agent, is the Agent, the Agent has a running command or delegated work still waiting to report back, its store predates the current schema, or the Agent is archived.
fnfunction	waitForAgentSettlement()	Await one exact durable terminal without opening a transcript observation.
fnfunction	createAgentControlSource()	Compose one authorized Agent-control projection for a single run lease.

AgentArchiveRefusedCclass

A host’s refusal to archive or restore an Agent, or to work with one that is archived. It reaches the caller as a failure of the operation it refused.

Extends

• Error

Constructors

Constructor

Signature

new AgentArchiveRefused(reason, message): AgentArchiveRefused;

Parameters

Parameter	Type
reason	| "running" | "pending" | "archived" | "not_creator" | "self" | "unreadable"
message	string

Returns

AgentArchiveRefused

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "AgentArchiveRefused" = "AgentArchiveRefused";

Overrides

Signature

Error.name;

reason

Signature

readonly reason:
  | "running"
  | "pending"
  | "archived"
  | "not_creator"
  | "self"
  | "unreadable";

---

AgentCreateRefusedCclass

A host’s refusal of an Agent creating an Agent: the creator asked to give the created Agent more than it holds, the host cannot tell which Agent is creating, or the request id belongs to another creating Agent or Session. It reaches the caller as an agents.create failure.

Extends

• Error

Constructors

Constructor

Signature

new AgentCreateRefused(reason, message): AgentCreateRefused;

Parameters

Parameter	Type
reason	"exceeds_creator" | "no_creator" | "request_conflict"
message	string

Returns

AgentCreateRefused

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "AgentCreateRefused" = "AgentCreateRefused";

Overrides

Signature

Error.name;

reason

Signature

readonly reason: "exceeds_creator" | "no_creator" | "request_conflict";

AgentControlAnswerInputTtype alias

Signature

type AgentControlAnswerInput = Readonly<{
  agentId: string;
  sessionId: string;
  askId: string;
  requestId: string;
  answers: MyceliumJsonValue;
}>;

Sender-authenticated submission for one child Session’s routed Ask.

---

AgentControlEscalateInputTtype alias

Signature

type AgentControlEscalateInput = Readonly<{
  agentId: string;
  sessionId: string;
  itemId: string;
  note?: string;
}>;

Sender-authenticated escalation of one item a child Session left waiting.

---

AgentControlAnswerOutputTtype alias

Signature

type AgentControlAnswerOutput = z.infer<typeof answerOutput>;

Typed outcome of a sender’s answer to a child Ask.

---

AgentControlEscalateOutputTtype alias

Signature

type AgentControlEscalateOutput = z.infer<typeof escalateOutput>;

Typed outcome of a sender’s escalation of a child’s item.

---

ArchiveRefusalReasonTtype alias

Signature

type ArchiveRefusalReason = (typeof archiveRefusalReasons)[number];

One reason in archiveRefusalReasons.

---

AgentControlAgentTtype alias

Signature

type AgentControlAgent = Readonly<{
  agentId: string;
  name: string;
  createdBy?: string | null;
  model?: ModelPreference;
  workingDirectory?: string;
}>;

One existing Agent visible within the caller’s authorized project or Team.

---

AgentControlModelTtype alias

Signature

type AgentControlModel = Readonly<{
  address: string;
  name: string;
}>;

One host-offered model usable as an Agent’s create or setModel choice.

---

AgentDelegationInputTtype alias

Signature

type AgentDelegationInput = Readonly<{
  agentId: string;
  text: string;
  requestId: string;
}> &
  | Readonly<{
  sessionId: string;
  delivery: "steer";
}>
  | Readonly<{
  sessionId?: string;
  delivery: "followUp";
}>;

One host-authorized delegation, with the caller Session supplied by acquisition.

---

AgentRecallInputTtype alias

Signature

type AgentRecallInput = Readonly<{
  agentId: string;
  sessionId: string;
  requestId: string;
}>;

Exact authorized destination and caller’s original send identity.

---

AgentDelegationInvocationTtype alias

Signature

type AgentDelegationInvocation = Readonly<{
  toolCallId: string;
  sendIndex: number;
  commandId?: string;
  meta?: CapabilitySession["meta"];
  toolCallCode?: string;
}>;

Host-only identity and admitted command metadata for one delegated send.

---

AgentControlDirectoryTtype alias

Signature

type AgentControlDirectory = Readonly<{
  list: (signal, options?) => Promise<readonly AgentControlAgent[]>;
  send?: (
    input,
    sourceSessionId,
    signal,
    invocation?,
  ) => Promise<Accepted | Held>;
  recall?: (input, sourceSessionId, signal) => Promise<CancelResult>;
  answer?: (
    input,
    senderSessionId,
    signal,
  ) => Promise<AgentControlAnswerOutput>;
  escalate?: (
    input,
    senderSessionId,
    signal,
  ) => Promise<AgentControlEscalateOutput>;
  create?: (input, signal) => Promise<AgentControlAgent>;
  setModel?: (input, signal) => Promise<void>;
  archive?: (input, signal) => Promise<void>;
  unarchive?: (input, signal) => Promise<void>;
  models?: (signal) => Promise<readonly AgentControlModel[]>;
  checkModel?: (input, signal) => Promise<void>;
  open: (
    agentId,
    signal,
  ) => Promise<
    Readonly<{
      agent: ShiitakeAgent;
      release: () => Promise<void>;
    }>
  >;
}>;

Host-owned discovery and per-operation access to ordinary Agents.

answerOutputconstconstant

Signature

const answerOutput: ZodDiscriminatedUnion<
  [
    ZodObject<
      {
        status: ZodLiteral<"answered">;
        via: ZodEnum<{
          in_turn: "in_turn";
          follow_up: "follow_up";
        }>;
        commandId: ZodExactOptional<ZodString>;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"not_found">;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"closed">;
        reason: ZodEnum<{
          cancelled: "cancelled";
          undeliverable: "undeliverable";
          answered: "answered";
          declined: "declined";
          withdrawn: "withdrawn";
          expired: "expired";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"refused">;
        reason: ZodEnum<{
          not_sender: "not_sender";
          no_provenance: "no_provenance";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"unavailable">;
        reason: ZodLiteral<"unsupported">;
      },
      $strict
    >,
  ],
  "status"
>;

Typed outcome of a sender’s answer to a child Ask.

---

escalateOutputconstconstant

Signature

const escalateOutput: ZodDiscriminatedUnion<
  [
    ZodObject<
      {
        status: ZodLiteral<"escalated">;
        to: ZodLiteral<"person">;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"not_found">;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"closed">;
        reason: ZodEnum<{
          cancelled: "cancelled";
          undeliverable: "undeliverable";
          answered: "answered";
          declined: "declined";
          withdrawn: "withdrawn";
          expired: "expired";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"refused">;
        reason: ZodEnum<{
          not_sender: "not_sender";
          no_provenance: "no_provenance";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"unavailable">;
        reason: ZodLiteral<"unsupported">;
      },
      $strict
    >,
  ],
  "status"
>;

Typed outcome of a sender’s escalation of a child’s item.

---

archiveRefusalReasonsconstconstant

Signature

const archiveRefusalReasons: readonly [
  "not_creator",
  "self",
  "running",
  "pending",
  "unreadable",
  "archived",
];

Why a host refuses an archive or restore: the caller did not create the Agent, is the Agent, the Agent has a running command or delegated work still waiting to report back, its store predates the current schema, or the Agent is archived.

waitForAgentSettlement()fnfunction

Signature

function waitForAgentSettlement(
  session,
  commandId,
  timeoutMs,
  signal,
  startedAt?,
): Promise<
  Readonly<{
    acceptedSender: string | null;
    delegator: string | null;
    terminal: SessionTerminal;
    content: string;
    usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[];
    toolCalls: number;
    waitingOnYou: readonly Readonly<{
      itemId: string;
      kind: string;
      summary: string;
    }>[];
  }>
>;

Await one exact durable terminal without opening a transcript observation.

Parameters

Parameter	Type
session	ShiitakeSession
commandId	string
timeoutMs	number
signal	AbortSignal
startedAt	number

Returns

Promise<Readonly<{ acceptedSender: string | null; delegator: string | null; terminal: SessionTerminal; content: string; usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[]; toolCalls: number; waitingOnYou: readonly Readonly<{ itemId: string; kind: string; summary: string; }>[]; }>>

---

createAgentControlSource()fnfunction

Signature

function createAgentControlSource(directory): CapabilitySource;

Compose one authorized Agent-control projection for a single run lease.

Parameters

Parameter	Type
directory	AgentControlDirectory

Returns

CapabilitySource