API reference

Exports

Kind	Export	Description
class	ApprovalLedger	SQLite lifecycle beside Mycelium. Native owner transactions serialize every transition.
type alias	PendingApproval	Deferred apply is delivered later through the existing Agent new-message path.
type alias	ApprovalEvidence	Metadata only: never raw image bytes, prose, URLs or executable content.
type alias	ApprovalRecord	Durable approval visible to every renderer.
type alias	ApprovalView	Current holder’s projection. A disabled button is not an authorization check.
type alias	ApprovalListInput	Bounded listing request.
type alias	ApprovalAnswerInput	Revision-pinned answer. No actor identity is accepted on the wire.
type alias	AutoApproveInput	One per-home or per-Agent module/access rule.
type alias	ApprovalRefusal	One typed refusal shared by answer/apply/policy entrypoints.
type alias	Approvals	The member-bound capability. Host authentication supplies the actor.
type alias	ApprovalHome	Native owner of this ledger; the Local runtime supplies its own SQLite owner.
type alias	ApprovalRequest	A request is host-attested metadata and JSON bytes, never renderer-provided identity.
type alias	AutoApproveQuery	Host-only policy read for an admitted Agent/module/access selection, not execution authority.
type alias	ApprovalAnswerer	Host-attested human identity and current authority over this exact operation.
type alias	ApprovalRuleSetter	Host-attested authority to write one auto-approve rule. A Team home resolves it against the exact rule: mayUseOperation for that family and mayManageAgent (agent.manage on that Agent; owners and admins hold it Team-wide). An answerer without mayManageAgent never manages an Agent. Oyster and Local homes are owner-only.
type alias	ApprovalAdmission	Mycelium owns admission; the ledger compares its opaque fence, never grant grammar.
type alias	ApprovalDispatchCompletion	Host verdict outside App JSON: only an attested zero-effect refusal is denied.
type alias	ApprovalApplyHost	Host-only adapter to the existing operation door; not an Agent continuation.
type alias	ApprovalSubmitHost	Only the submitting capability may attach evidence; never spread tool input here.
type alias	ApprovalApplyResult	Private result for inline tool output or ordinary deferred new-message delivery.
type alias	ApprovalResultNotice	Deferred result cargo; stored request input is not a field on this port.
type alias	ApprovalHandoffResult	Ordinary new-message receipt, explicit no-delivery result, or typed refusal.
constant	ApprovalAccessSchema	The effect class is independent of reversibility; ON includes both.
constant	ApprovalFamilySchema	One operation module, or every module when module is null.
constant	ApprovalScopeSchema	One requesting Agent, or the entire home when agentId is null.
constant	ApprovalRequesterSchema	Stable requester identity supplied by the host, never by tool arguments.
constant	ApprovalDescriptionSchema	A renderer sees metadata and a byte digest, never the proposed input.
constant	PendingApprovalSchema	Immediate normal tool result: no effect ran and no Agent turn is suspended.
constant	ApprovalStateSchema	All renderers use these same durable lifecycle states.
constant	ApprovalRefusalReasonSchema	Why a decision or apply was refused; unknown dispatch is never a denial.
constant	MAX_APPROVAL_DENIAL_NOTE_LENGTH	Human explanation for a denied approval; distinct from the typed refusal cause.
constant	ApprovalDenialNoteSchema	Bounded nonempty human feedback; user text, never approval authority.
constant	MAX_APPROVAL_EVIDENCE	Defensive display limits, not authority to fetch or interpret image content.
constant	MAX_APPROVAL_EVIDENCE_BYTES	Maximum attested PNG byte length in one evidence descriptor.
constant	ApprovalEvidenceSchema	Capability-attested content address; image bytes remain untrusted display-only data.
constant	ApprovalRecordSchema	Public record. Effect input, output and executable continuations stay host-private.
constant	ApprovalViewSchema	Rights are recomputed for the holder on each read, not persisted on the record.
constant	ApprovalListInputSchema	Bounded reads with an opaque storage cursor.
constant	ApprovalGetInputSchema	Locate one public view without carrying actor identity in request data.
constant	ApprovalAnswerInputSchema	An answer is a decision, never a confirm-labelled write itself.
constant	AutoApproveInputSchema	Explicit policy mutation. A false rule narrows a broader true rule.
constant	ApprovalRefusalSchema	Canonical zero-effect or lifecycle refusal at a tool result boundary.
constant	DEFAULT_APPROVAL_EXPIRY_MS	The initial owner-controlled wait duration; passing the deadline never approves.
function	denialFeedbackOpening()	Host-supplied human identity; the bounded reason remains quoted user text.

ApprovalLedgerclass

SQLite lifecycle beside Mycelium. Native owner transactions serialize every transition.

Constructors

Constructor

new ApprovalLedger(options): ApprovalLedger;

Parameters

Parameter	Type
`options`	`Readonly<{ owner: WatchdogSqliteOwner; home: ApprovalHome; now: () => number; persistIntent?: (record) => undefined; resultDelivery?: Readonly<{ retryDelay: (attempt) => number; attemptLimit: number; }>; }>`

Returns

ApprovalLedger

Methods

capability()

capability(host): Approvals;

Bound control surface; null identity means membership is gone, never an impersonated key.

Parameters

Parameter	Type
`host`	`Readonly<{ actor: (record) => Promise<ApprovalAnswerer \| null>; decision: (recordId) => Promise<void>; setter?: (rule) => Promise<ApprovalRuleSetter \| null>; }>`

Returns

Approvals

submit()

submit(input, host): Promise<
  | {
  kind: "pending_approval";
  recordId: string;
  description: {
     title: string;
     inputBytes: number;
     inputSha256: string;
  };
}
| ApprovalApplyResult>;

Normal tool admission returns pending immediately, or applies policy approval inline.

Parameters

Parameter	Type
`input`	`ApprovalRequest`
`host`	`ApprovalSubmitHost`

Returns

Promise< | { kind: "pending_approval"; recordId: string; description: { title: string; inputBytes: number; inputSha256: string; }; } | ApprovalApplyResult>

outcome()

outcome(record):
  | {
  kind: "pending_approval";
  recordId: string;
  description: {
     title: string;
     inputBytes: number;
     inputSha256: string;
  };
}
  | ApprovalApplyResult;

A retried request’s current outcome, without claiming any work.

Parameters

Parameter	Type
`record`	{ recordId: string; requester: { principalId: string; agentId: string \| null; sessionId: string \| null; displayName: string; }; module: string; operation: string; access: "write" \| "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" \| "irreversible-external"; state: \| "pending" \| "expired" \| "denied" \| "requested" \| "approved" \| "claimed" \| "applied" \| "outcome_unknown"; by: \| { kind: "human"; memberId: string; } \| { kind: "policy"; } \| null; reason: \| "pending" \| "expired" \| "not-found" \| "not-eligible" \| "already-answered" \| "stale-revision" \| "declined" \| "fenced" \| "not-granted" \| "read-only" \| "in-flight" \| "outcome-unknown" \| "identity-conflict" \| null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }
`record.recordId`	`string`
`record.requester`	`{ principalId: string; agentId: string \| null; sessionId: string \| null; displayName: string; }`
`record.requester.principalId`	`string`
`record.requester.agentId`	`string \| null`
`record.requester.sessionId`	`string \| null`
`record.requester.displayName`	`string`
`record.module`	`string`
`record.operation`	`string`
`record.access`	`"write" \| "external"`
`record.description`	`{ title: string; inputBytes: number; inputSha256: string; }`
`record.description.title`	`string`
`record.description.inputBytes`	`number`
`record.description.inputSha256`	`string`
`record.evidence?`	`readonly object[]`
`record.authorityFence`	`string`
`record.reversibility`	`"reversible" \| "irreversible-external"`
`record.state`	`\| "pending" \| "expired" \| "denied" \| "requested" \| "approved" \| "claimed" \| "applied" \| "outcome_unknown"`
`record.by`	`\| { kind: "human"; memberId: string; } \| { kind: "policy"; } \| null`
`record.reason`	`\| "pending" \| "expired" \| "not-found" \| "not-eligible" \| "already-answered" \| "stale-revision" \| "declined" \| "fenced" \| "not-granted" \| "read-only" \| "in-flight" \| "outcome-unknown" \| "identity-conflict" \| null`
`record.denialNote?`	`string`
`record.requestedAt`	`number`
`record.expiresAt`	`number`
`record.updatedAt`	`number`
`record.revision`	`number`

Returns

| { kind: "pending_approval"; recordId: string; description: { title: string; inputBytes: number; inputSha256: string; }; } | ApprovalApplyResult

request()

request(input, evidence?): Promise<
  | Readonly<{
  kind: "refused";
  reason:   | "pending"
     | "expired"
     | "not-found"
     | "not-eligible"
     | "already-answered"
     | "stale-revision"
     | "declined"
     | "fenced"
     | "not-granted"
     | "read-only"
     | "in-flight"
     | "outcome-unknown"
     | "identity-conflict";
  denialNote?: string;
}>
  | Readonly<{
  kind: "record";
  record: {
     recordId: string;
     requester: {
        principalId: string;
        agentId: string | null;
        sessionId: string | null;
        displayName: string;
     };
     module: string;
     operation: string;
     access: "write" | "external";
     description: {
        title: string;
        inputBytes: number;
        inputSha256: string;
     };
     evidence?: readonly object[];
     authorityFence: string;
     reversibility: "reversible" | "irreversible-external";
     state:   | "pending"
        | "expired"
        | "denied"
        | "requested"
        | "approved"
        | "claimed"
        | "applied"
        | "outcome_unknown";
     by:   | {
        kind: "human";
        memberId: string;
      }
        | {
        kind: "policy";
      }
        | null;
     reason:   | "pending"
        | "expired"
        | "not-found"
        | "not-eligible"
        | "already-answered"
        | "stale-revision"
        | "declined"
        | "fenced"
        | "not-granted"
        | "read-only"
        | "in-flight"
        | "outcome-unknown"
        | "identity-conflict"
        | null;
     denialNote?: string;
     requestedAt: number;
     expiresAt: number;
     updatedAt: number;
     revision: number;
  };
  created: boolean;
}>>;

Stage one stable intended effect. Duplicate identities never create another action; created says whether this call staged the record.

Parameters

Parameter	Type
`input`	`ApprovalRequest`
`evidence?`	`readonly object[]`

Returns

Promise< | Readonly<{ kind: "refused"; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict"; denialNote?: string; }> | Readonly<{ kind: "record"; record: { recordId: string; requester: { principalId: string; agentId: string | null; sessionId: string | null; displayName: string; }; module: string; operation: string; access: "write" | "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" | "irreversible-external"; state: | "pending" | "expired" | "denied" | "requested" | "approved" | "claimed" | "applied" | "outcome_unknown"; by: | { kind: "human"; memberId: string; } | { kind: "policy"; } | null; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }; created: boolean; }>>

answer()

answer(input, actor):
  | Readonly<{
  kind: "refused";
  reason:   | "pending"
     | "expired"
     | "not-found"
     | "not-eligible"
     | "already-answered"
     | "stale-revision"
     | "declined"
     | "fenced"
     | "not-granted"
     | "read-only"
     | "in-flight"
     | "outcome-unknown"
     | "identity-conflict";
  denialNote?: string;
}>
  | Readonly<{
  kind: "answered";
  record: {
     recordId: string;
     requester: {
        principalId: string;
        agentId: string | null;
        sessionId: string | null;
        displayName: string;
     };
     module: string;
     operation: string;
     access: "write" | "external";
     description: {
        title: string;
        inputBytes: number;
        inputSha256: string;
     };
     evidence?: readonly object[];
     authorityFence: string;
     reversibility: "reversible" | "irreversible-external";
     state:   | "pending"
        | "expired"
        | "denied"
        | "requested"
        | "approved"
        | "claimed"
        | "applied"
        | "outcome_unknown";
     by:   | {
        kind: "human";
        memberId: string;
      }
        | {
        kind: "policy";
      }
        | null;
     reason:   | "pending"
        | "expired"
        | "not-found"
        | "not-eligible"
        | "already-answered"
        | "stale-revision"
        | "declined"
        | "fenced"
        | "not-granted"
        | "read-only"
        | "in-flight"
        | "outcome-unknown"
        | "identity-conflict"
        | null;
     denialNote?: string;
     requestedAt: number;
     expiresAt: number;
     updatedAt: number;
     revision: number;
  };
}>;

Answering is revision-pinned and never changes the requester’s underlying grants.

Parameters

Parameter	Type
`input`	`{ recordId: string; decision: "approve" \| "deny"; expectedRevision: number; denialNote?: string; }`
`input.recordId`	`string`
`input.decision`	`"approve" \| "deny"`
`input.expectedRevision`	`number`
`input.denialNote?`	`string`
`actor`	`ApprovalAnswerer \| null`

Returns

| Readonly<{ kind: "refused"; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict"; denialNote?: string; }> | Readonly<{ kind: "answered"; record: { recordId: string; requester: { principalId: string; agentId: string | null; sessionId: string | null; displayName: string; }; module: string; operation: string; access: "write" | "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" | "irreversible-external"; state: | "pending" | "expired" | "denied" | "requested" | "approved" | "claimed" | "applied" | "outcome_unknown"; by: | { kind: "human"; memberId: string; } | { kind: "policy"; } | null; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }; }>

setAutoApprove()

setAutoApprove(input, setter):
  | Readonly<{
  kind: "refused";
  reason:   | "pending"
     | "expired"
     | "not-found"
     | "not-eligible"
     | "already-answered"
     | "stale-revision"
     | "declined"
     | "fenced"
     | "not-granted"
     | "read-only"
     | "in-flight"
     | "outcome-unknown"
     | "identity-conflict";
  denialNote?: string;
}>
  | Readonly<{
  kind: "updated";
  rule: {
     scope: {
        agentId: string | null;
     };
     family: {
        module: string | null;
        access: "write" | "external";
     };
     enabled: boolean;
  };
}>;

Policy changes are attributed; an Agent can never enable its own writes.

Parameters

Parameter	Type
`input`	`{ scope: { agentId: string \| null; }; family: { module: string \| null; access: "write" \| "external"; }; enabled: boolean; }`
`input.scope`	`{ agentId: string \| null; }`
`input.scope.agentId`	`string \| null`
`input.family`	`{ module: string \| null; access: "write" \| "external"; }`
`input.family.module`	`string \| null`
`input.family.access`	`"write" \| "external"`
`input.enabled`	`boolean`
`setter`	`ApprovalRuleSetter \| null`

Returns

| Readonly<{ kind: "refused"; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict"; denialNote?: string; }> | Readonly<{ kind: "updated"; rule: { scope: { agentId: string | null; }; family: { module: string | null; access: "write" | "external"; }; enabled: boolean; }; }>

selectAutoApprove()

selectAutoApprove(query): boolean;

Pure policy selection: no record, claim, dispatch, grant widening or containment choice.

Parameters

Parameter	Type
`query`	`AutoApproveQuery`

Returns

boolean

expirePending()

expirePending(): void;

Expire one bounded home-local quantum without a member read or an approval.

Returns

void

nextWakeAt()

nextWakeAt(): number | null;

Earliest native wake for waiting or unfinished effects; no claim or dispatch.

Returns

number | null

pendingApplications()

pendingApplications(): readonly string[];

Bounded approved work for the native owner; selection never claims or dispatches.

Returns

readonly string[]

readInput()

readInput(recordId): Json;

Host-private display recovery; never exposed by the member-bound capability.

Parameters

Parameter	Type
`recordId`	`string`

Returns

Json

pendingHandoffs()

pendingHandoffs(): readonly string[];

Bounded, home-local terminal notices for the native owner’s work loop.

Returns

readonly string[]

handoff()

handoff(recordId, send): Promise<ApprovalHandoffResult>;

Retry only the ordinary message, with the same recipient-side idempotency key. A send rejection leaves the intent pending; it never reopens effect execution. The host must return the real Session acceptance, not a success-shaped placeholder.

Parameters

Parameter	Type
`recordId`	`string`
`send`	`(notice) => Promise<Readonly<{ commandId: string; }>>`

Returns

Promise<ApprovalHandoffResult>

apply()

apply(recordId, host): Promise<ApprovalApplyResult>;

The home’s work loop: only a durable approved record claims the existing host operation, and its result always reaches a waiting Agent as a message.

Parameters

Parameter	Type
`recordId`	`string`
`host`	`ApprovalApplyHost`

Returns

Promise<ApprovalApplyResult>

applyInline()

applyInline(recordId, host): Promise<ApprovalApplyResult>;

Apply the caller’s own just-staged policy approval inside its live tool call; that call’s result is the outcome, so no later message is owed.

Parameters

Parameter	Type
`recordId`	`string`
`host`	`ApprovalApplyHost`

Returns

Promise<ApprovalApplyResult>

recoverClaims()

recoverClaims(): readonly object[];

Native host boot only: orphaned durable claims must never be redispatched.

Returns

readonly object[]

get()

get(recordId):
  | {
  recordId: string;
  requester: {
     principalId: string;
     agentId: string | null;
     sessionId: string | null;
     displayName: string;
  };
  module: string;
  operation: string;
  access: "write" | "external";
  description: {
     title: string;
     inputBytes: number;
     inputSha256: string;
  };
  evidence?: readonly object[];
  authorityFence: string;
  reversibility: "reversible" | "irreversible-external";
  state:   | "pending"
     | "expired"
     | "denied"
     | "requested"
     | "approved"
     | "claimed"
     | "applied"
     | "outcome_unknown";
  by:   | {
     kind: "human";
     memberId: string;
   }
     | {
     kind: "policy";
   }
     | null;
  reason:   | "pending"
     | "expired"
     | "not-found"
     | "not-eligible"
     | "already-answered"
     | "stale-revision"
     | "declined"
     | "fenced"
     | "not-granted"
     | "read-only"
     | "in-flight"
     | "outcome-unknown"
     | "identity-conflict"
     | null;
  denialNote?: string;
  requestedAt: number;
  expiresAt: number;
  updatedAt: number;
  revision: number;
}
  | null;

Read a record from this home only; the maintained decoder owns stored JSON.

Parameters

Parameter	Type
`recordId`	`string`

Returns

| { recordId: string; requester: { principalId: string; agentId: string | null; sessionId: string | null; displayName: string; }; module: string; operation: string; access: "write" | "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" | "irreversible-external"; state: | "pending" | "expired" | "denied" | "requested" | "approved" | "claimed" | "applied" | "outcome_unknown"; by: | { kind: "human"; memberId: string; } | { kind: "policy"; } | null; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; } | null

PendingApprovaltype alias

type PendingApproval = typeof PendingApprovalSchema.Type;

Deferred apply is delivered later through the existing Agent new-message path.

ApprovalEvidencetype alias

type ApprovalEvidence = typeof ApprovalEvidenceSchema.Type;

Metadata only: never raw image bytes, prose, URLs or executable content.

ApprovalRecordtype alias

type ApprovalRecord = typeof ApprovalRecordSchema.Type;

Durable approval visible to every renderer.

ApprovalViewtype alias

type ApprovalView = typeof ApprovalViewSchema.Type;

Current holder’s projection. A disabled button is not an authorization check.

ApprovalListInputtype alias

type ApprovalListInput = typeof ApprovalListInputSchema.Type;

Bounded listing request.

ApprovalAnswerInputtype alias

type ApprovalAnswerInput = typeof ApprovalAnswerInputSchema.Type;

Revision-pinned answer. No actor identity is accepted on the wire.

AutoApproveInputtype alias

type AutoApproveInput = typeof AutoApproveInputSchema.Type;

One per-home or per-Agent module/access rule.

ApprovalRefusaltype alias

type ApprovalRefusal = Readonly<{
  kind: "refused";
  reason: typeof ApprovalRefusalReasonSchema.Type;
  denialNote?: typeof ApprovalDenialNoteSchema.Type;
}>;

One typed refusal shared by answer/apply/policy entrypoints.

Approvalstype alias

type Approvals = Readonly<{
  list: Promise<
    Readonly<{
      items: readonly ApprovalView[];
      nextCursor: string | null;
    }>
  >;
  get: Promise<{
    record: {
      recordId: string;
      requester: {
        principalId: string;
        agentId: string | null;
        sessionId: string | null;
        displayName: string;
      };
      module: string;
      operation: string;
      access: "write" | "external";
      description: {
        title: string;
        inputBytes: number;
        inputSha256: string;
      };
      evidence?: readonly object[];
      authorityFence: string;
      reversibility: "reversible" | "irreversible-external";
      state:
        | "pending"
        | "expired"
        | "denied"
        | "requested"
        | "approved"
        | "claimed"
        | "applied"
        | "outcome_unknown";
      by:
        | {
            kind: "human";
            memberId: string;
          }
        | {
            kind: "policy";
          }
        | null;
      reason:
        | "pending"
        | "expired"
        | "not-found"
        | "not-eligible"
        | "already-answered"
        | "stale-revision"
        | "declined"
        | "fenced"
        | "not-granted"
        | "read-only"
        | "in-flight"
        | "outcome-unknown"
        | "identity-conflict"
        | null;
      denialNote?: string;
      requestedAt: number;
      expiresAt: number;
      updatedAt: number;
      revision: number;
    };
    canAnswer: boolean;
    canSetAutoApprove: boolean;
  } | null>;
  answer: Promise<
    | Readonly<{
        kind: "refused";
        reason: typeof ApprovalRefusalReasonSchema.Type;
        denialNote?: typeof ApprovalDenialNoteSchema.Type;
      }>
    | Readonly<{
        kind: "answered";
        view: ApprovalView;
      }>
  >;
  setAutoApprove: Promise<
    | Readonly<{
        kind: "refused";
        reason: typeof ApprovalRefusalReasonSchema.Type;
        denialNote?: typeof ApprovalDenialNoteSchema.Type;
      }>
    | Readonly<{
        kind: "updated";
        rule: AutoApproveInput;
      }>
  >;
}>;

The member-bound capability. Host authentication supplies the actor.

ApprovalHometype alias

type ApprovalHome = Readonly<{
  kind: "team" | "oyster" | "local";
  id: string;
}>;

Native owner of this ledger; the Local runtime supplies its own SQLite owner.

ApprovalRequesttype alias

type ApprovalRequest = Readonly<{
  requester: ApprovalRecord["requester"];
  module: string;
  operation: string;
  access: ApprovalRecord["access"];
  reversibility: ApprovalRecord["reversibility"];
  authorityFence: string;
  idempotencyKey: string;
  inputJson: string;
  requireHumanApproval?: boolean;
  prefixPolicyApproved?: boolean;
}>;

A request is host-attested metadata and JSON bytes, never renderer-provided identity.

AutoApproveQuerytype alias

type AutoApproveQuery = Readonly<{
  agentId: ApprovalRequest["requester"]["agentId"];
  module: ApprovalRequest["module"];
  access: ApprovalRequest["access"];
}>;

Host-only policy read for an admitted Agent/module/access selection, not execution authority.

ApprovalAnswerertype alias

type ApprovalAnswerer =
  | Readonly<{
      kind: "human";
      memberId: string;
      role: "owner" | "admin" | "member";
      actingForAgent: boolean;
      mayUseOperation: boolean;
    }>
  | Readonly<{
      kind: "agent" | "key";
    }>;

Host-attested human identity and current authority over this exact operation.

ApprovalRuleSettertype alias

type ApprovalRuleSetter =
  | ApprovalAnswerer
  | (Extract<
      ApprovalAnswerer,
      {
        kind: "human";
      }
    > &
      Readonly<{
        mayManageAgent: boolean;
      }>);

Host-attested authority to write one auto-approve rule. A Team home resolves it against the exact rule: mayUseOperation for that family and mayManageAgent (agent.manage on that Agent; owners and admins hold it Team-wide). An answerer without mayManageAgent never manages an Agent. Oyster and Local homes are owner-only.

ApprovalAdmissiontype alias

type ApprovalAdmission =
  | Readonly<{
      kind: "authorized";
      authorityFence: string;
    }>
  | Readonly<{
      kind: "refused";
      reason: "not-granted" | "read-only";
    }>;

Mycelium owns admission; the ledger compares its opaque fence, never grant grammar.

ApprovalDispatchCompletiontype alias

type ApprovalDispatchCompletion =
  | Readonly<{
      kind: "completed";
      output: typeof Schema.Json.Type;
    }>
  | Readonly<{
      kind: "refused";
      reason: "not-granted" | "read-only";
    }>;

Host verdict outside App JSON: only an attested zero-effect refusal is denied.

ApprovalApplyHosttype alias

type ApprovalApplyHost = Readonly<{
  recheck: (record) => Promise<ApprovalAdmission>;
  dispatch: (request) => Promise<ApprovalDispatchCompletion>;
}>;

Host-only adapter to the existing operation door; not an Agent continuation.

ApprovalSubmitHosttype alias

type ApprovalSubmitHost = ApprovalApplyHost &
  Readonly<{
    evidence?: ApprovalEvidence;
  }>;

Only the submitting capability may attach evidence; never spread tool input here.

ApprovalApplyResulttype alias

type ApprovalApplyResult =
  | Readonly<{
      kind: "applied";
      record: ApprovalRecord;
      output: typeof Schema.Json.Type;
    }>
  | ApprovalRefusal;

Private result for inline tool output or ordinary deferred new-message delivery.

ApprovalResultNoticetype alias

type ApprovalResultNotice = Readonly<{
  deliveryId: string;
  record: ApprovalRecord;
  result: ApprovalApplyResult;
}>;

Deferred result cargo; stored request input is not a field on this port.

ApprovalHandoffResulttype alias

type ApprovalHandoffResult =
  | Readonly<{
      kind: "delivered";
      commandId: string;
    }>
  | Readonly<{
      kind: "not-required";
    }>
  | Readonly<{
      kind: "undeliverable";
    }>
  | ApprovalRefusal;

Ordinary new-message receipt, explicit no-delivery result, or typed refusal.

ApprovalAccessSchemaconstant

const ApprovalAccessSchema: Literals<readonly ["write", "external"]>;

The effect class is independent of reversibility; ON includes both.

ApprovalFamilySchemaconstant

const ApprovalFamilySchema: Struct<{
  module: NullOr<String>;
  access: Literals<readonly ["write", "external"]>;
}>;

One operation module, or every module when module is null.

ApprovalScopeSchemaconstant

const ApprovalScopeSchema: Struct<{
  agentId: NullOr<String>;
}>;

One requesting Agent, or the entire home when agentId is null.

ApprovalRequesterSchemaconstant

const ApprovalRequesterSchema: Struct<{
  principalId: String;
  agentId: NullOr<String>;
  sessionId: NullOr<String>;
  displayName: String;
}>;

Stable requester identity supplied by the host, never by tool arguments.

ApprovalDescriptionSchemaconstant

const ApprovalDescriptionSchema: Struct<{
  title: String;
  inputBytes: Int;
  inputSha256: String;
}>;

A renderer sees metadata and a byte digest, never the proposed input.

PendingApprovalSchemaconstant

const PendingApprovalSchema: Struct<{
  kind: Literal<"pending_approval">;
  recordId: String;
  description: Struct<{
    title: String;
    inputBytes: Int;
    inputSha256: String;
  }>;
}>;

Immediate normal tool result: no effect ran and no Agent turn is suspended.

ApprovalStateSchemaconstant

const ApprovalStateSchema: Literals<
  readonly [
    "requested",
    "pending",
    "approved",
    "claimed",
    "applied",
    "denied",
    "expired",
    "outcome_unknown",
  ]
>;

All renderers use these same durable lifecycle states.

ApprovalRefusalReasonSchemaconstant

const ApprovalRefusalReasonSchema: Literals<
  readonly [
    "not-found",
    "not-eligible",
    "already-answered",
    "stale-revision",
    "expired",
    "declined",
    "fenced",
    "not-granted",
    "read-only",
    "pending",
    "in-flight",
    "outcome-unknown",
    "identity-conflict",
  ]
>;

Why a decision or apply was refused; unknown dispatch is never a denial.

MAX_APPROVAL_DENIAL_NOTE_LENGTHconstant

const MAX_APPROVAL_DENIAL_NOTE_LENGTH: 512 = 512;

Human explanation for a denied approval; distinct from the typed refusal cause.

ApprovalDenialNoteSchemaconstant

const ApprovalDenialNoteSchema: String;

Bounded nonempty human feedback; user text, never approval authority.

MAX_APPROVAL_EVIDENCEconstant

const MAX_APPROVAL_EVIDENCE: 4 = 4;

Defensive display limits, not authority to fetch or interpret image content.

MAX_APPROVAL_EVIDENCE_BYTESconstant

const MAX_APPROVAL_EVIDENCE_BYTES: number;

Maximum attested PNG byte length in one evidence descriptor.

ApprovalEvidenceSchemaconstant

const ApprovalEvidenceSchema: $Array<
  Struct<{
    kind: Literal<"artifact">;
    ref: String;
    mediaType: Literal<"image/png">;
    bytes: Int;
  }>
>;

Capability-attested content address; image bytes remain untrusted display-only data.

ApprovalRecordSchemaconstant

const ApprovalRecordSchema: Struct<{
  recordId: String;
  requester: Struct<{
    principalId: String;
    agentId: NullOr<String>;
    sessionId: NullOr<String>;
    displayName: String;
  }>;
  module: String;
  operation: String;
  access: Literals<readonly ["write", "external"]>;
  description: Struct<{
    title: String;
    inputBytes: Int;
    inputSha256: String;
  }>;
  evidence: optionalKey<
    $Array<
      Struct<{
        kind: Literal<"artifact">;
        ref: String;
        mediaType: Literal<"image/png">;
        bytes: Int;
      }>
    >
  >;
  authorityFence: String;
  reversibility: Literals<readonly ["reversible", "irreversible-external"]>;
  state: Literals<
    readonly [
      "requested",
      "pending",
      "approved",
      "claimed",
      "applied",
      "denied",
      "expired",
      "outcome_unknown",
    ]
  >;
  by: NullOr<
    Union<
      readonly [
        Struct<{
          kind: Literal<"human">;
          memberId: String;
        }>,
        Struct<{
          kind: Literal<"policy">;
        }>,
      ]
    >
  >;
  reason: NullOr<
    Literals<
      readonly [
        "not-found",
        "not-eligible",
        "already-answered",
        "stale-revision",
        "expired",
        "declined",
        "fenced",
        "not-granted",
        "read-only",
        "pending",
        "in-flight",
        "outcome-unknown",
        "identity-conflict",
      ]
    >
  >;
  denialNote: optionalKey<String>;
  requestedAt: Int;
  expiresAt: Int;
  updatedAt: Int;
  revision: Int;
}>;

Public record. Effect input, output and executable continuations stay host-private.

ApprovalViewSchemaconstant

const ApprovalViewSchema: Struct<{
  record: Struct<{
    recordId: String;
    requester: Struct<{
      principalId: String;
      agentId: NullOr<String>;
      sessionId: NullOr<String>;
      displayName: String;
    }>;
    module: String;
    operation: String;
    access: Literals<readonly ["write", "external"]>;
    description: Struct<{
      title: String;
      inputBytes: Int;
      inputSha256: String;
    }>;
    evidence: optionalKey<
      $Array<
        Struct<{
          kind: Literal<"artifact">;
          ref: String;
          mediaType: Literal<"image/png">;
          bytes: Int;
        }>
      >
    >;
    authorityFence: String;
    reversibility: Literals<readonly ["reversible", "irreversible-external"]>;
    state: Literals<
      readonly [
        "requested",
        "pending",
        "approved",
        "claimed",
        "applied",
        "denied",
        "expired",
        "outcome_unknown",
      ]
    >;
    by: NullOr<
      Union<
        readonly [
          Struct<{
            kind: Literal<"human">;
            memberId: String;
          }>,
          Struct<{
            kind: Literal<"policy">;
          }>,
        ]
      >
    >;
    reason: NullOr<
      Literals<
        readonly [
          "not-found",
          "not-eligible",
          "already-answered",
          "stale-revision",
          "expired",
          "declined",
          "fenced",
          "not-granted",
          "read-only",
          "pending",
          "in-flight",
          "outcome-unknown",
          "identity-conflict",
        ]
      >
    >;
    denialNote: optionalKey<String>;
    requestedAt: Int;
    expiresAt: Int;
    updatedAt: Int;
    revision: Int;
  }>;
  canAnswer: Boolean;
  canSetAutoApprove: Boolean;
}>;

Rights are recomputed for the holder on each read, not persisted on the record.

ApprovalListInputSchemaconstant

const ApprovalListInputSchema: Struct<{
  state: optionalKey<
    Literals<
      readonly [
        "requested",
        "pending",
        "approved",
        "claimed",
        "applied",
        "denied",
        "expired",
        "outcome_unknown",
      ]
    >
  >;
  cursor: optionalKey<String>;
  limit: optionalKey<Int>;
}>;

Bounded reads with an opaque storage cursor.

ApprovalGetInputSchemaconstant

const ApprovalGetInputSchema: Struct<{
  recordId: String;
}>;

Locate one public view without carrying actor identity in request data.

ApprovalAnswerInputSchemaconstant

const ApprovalAnswerInputSchema: Struct<{
  recordId: String;
  decision: Literals<readonly ["approve", "deny"]>;
  expectedRevision: Int;
  denialNote: optionalKey<String>;
}>;

An answer is a decision, never a confirm-labelled write itself.

AutoApproveInputSchemaconstant

const AutoApproveInputSchema: Struct<{
  scope: Struct<{
    agentId: NullOr<String>;
  }>;
  family: Struct<{
    module: NullOr<String>;
    access: Literals<readonly ["write", "external"]>;
  }>;
  enabled: Boolean;
}>;

Explicit policy mutation. A false rule narrows a broader true rule.

ApprovalRefusalSchemaconstant

const ApprovalRefusalSchema: Struct<{
  kind: Literal<"refused">;
  reason: Literals<
    readonly [
      "not-found",
      "not-eligible",
      "already-answered",
      "stale-revision",
      "expired",
      "declined",
      "fenced",
      "not-granted",
      "read-only",
      "pending",
      "in-flight",
      "outcome-unknown",
      "identity-conflict",
    ]
  >;
  denialNote: optionalKey<String>;
}>;

Canonical zero-effect or lifecycle refusal at a tool result boundary.

DEFAULT_APPROVAL_EXPIRY_MSconstant

const DEFAULT_APPROVAL_EXPIRY_MS: number;

The initial owner-controlled wait duration; passing the deadline never approves.

denialFeedbackOpening()function

function denialFeedbackOpening(record, person): string | null;

Host-supplied human identity; the bounded reason remains quoted user text.

Parameters

Parameter	Type
`record`	{ recordId: string; requester: { principalId: string; agentId: string \| null; sessionId: string \| null; displayName: string; }; module: string; operation: string; access: "write" \| "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" \| "irreversible-external"; state: \| "pending" \| "expired" \| "denied" \| "requested" \| "approved" \| "claimed" \| "applied" \| "outcome_unknown"; by: \| { kind: "human"; memberId: string; } \| { kind: "policy"; } \| null; reason: \| "pending" \| "expired" \| "not-found" \| "not-eligible" \| "already-answered" \| "stale-revision" \| "declined" \| "fenced" \| "not-granted" \| "read-only" \| "in-flight" \| "outcome-unknown" \| "identity-conflict" \| null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }
`record.recordId`	`string`
`record.requester`	`{ principalId: string; agentId: string \| null; sessionId: string \| null; displayName: string; }`
`record.requester.principalId`	`string`
`record.requester.agentId`	`string \| null`
`record.requester.sessionId`	`string \| null`
`record.requester.displayName`	`string`
`record.module`	`string`
`record.operation`	`string`
`record.access`	`"write" \| "external"`
`record.description`	`{ title: string; inputBytes: number; inputSha256: string; }`
`record.description.title`	`string`
`record.description.inputBytes`	`number`
`record.description.inputSha256`	`string`
`record.evidence?`	`readonly object[]`
`record.authorityFence`	`string`
`record.reversibility`	`"reversible" \| "irreversible-external"`
`record.state`	`\| "pending" \| "expired" \| "denied" \| "requested" \| "approved" \| "claimed" \| "applied" \| "outcome_unknown"`
`record.by`	`\| { kind: "human"; memberId: string; } \| { kind: "policy"; } \| null`
`record.reason`	`\| "pending" \| "expired" \| "not-found" \| "not-eligible" \| "already-answered" \| "stale-revision" \| "declined" \| "fenced" \| "not-granted" \| "read-only" \| "in-flight" \| "outcome-unknown" \| "identity-conflict" \| null`
`record.denialNote?`	`string`
`record.requestedAt`	`number`
`record.expiresAt`	`number`
`record.updatedAt`	`number`
`record.revision`	`number`
`person`	`string`

Returns

string | null

API reference

Exports

ApprovalLedgerCclass

Constructors

Constructor

Parameters

Returns

Methods

capability()

Parameters

Returns

submit()

Parameters

Returns

outcome()

Parameters

Returns

request()

Parameters

Returns

answer()

Parameters

Returns

setAutoApprove()

Parameters

Returns

selectAutoApprove()

Parameters

Returns

expirePending()

Returns

nextWakeAt()

Returns

pendingApplications()

Returns

readInput()

Parameters

Returns

pendingHandoffs()

Returns

handoff()

Parameters

Returns

apply()

Parameters

Returns

applyInline()

Parameters

Returns

recoverClaims()

Returns

get()

Parameters

Returns

PendingApprovalTtype alias

ApprovalEvidenceTtype alias

ApprovalRecordTtype alias

ApprovalViewTtype alias

ApprovalListInputTtype alias

ApprovalAnswerInputTtype alias

AutoApproveInputTtype alias

ApprovalRefusalTtype alias

ApprovalsTtype alias

ApprovalHomeTtype alias

ApprovalRequestTtype alias

AutoApproveQueryTtype alias

ApprovalAnswererTtype alias

ApprovalRuleSetterTtype alias

ApprovalAdmissionTtype alias

ApprovalDispatchCompletionTtype alias

ApprovalApplyHostTtype alias

ApprovalSubmitHostTtype alias

ApprovalApplyResultTtype alias

ApprovalResultNoticeTtype alias

ApprovalHandoffResultTtype alias

ApprovalAccessSchemaconstconstant

ApprovalFamilySchemaconstconstant

ApprovalScopeSchemaconstconstant

ApprovalRequesterSchemaconstconstant

ApprovalDescriptionSchemaconstconstant

ApprovalLedgerclass

PendingApprovaltype alias

ApprovalEvidencetype alias

ApprovalRecordtype alias

ApprovalViewtype alias

ApprovalListInputtype alias

ApprovalAnswerInputtype alias

AutoApproveInputtype alias

ApprovalRefusaltype alias

Approvalstype alias

ApprovalHometype alias

ApprovalRequesttype alias

AutoApproveQuerytype alias

ApprovalAnswerertype alias

ApprovalRuleSettertype alias

ApprovalAdmissiontype alias

ApprovalDispatchCompletiontype alias

ApprovalApplyHosttype alias

ApprovalSubmitHosttype alias

ApprovalApplyResulttype alias

ApprovalResultNoticetype alias

ApprovalHandoffResulttype alias

ApprovalAccessSchemaconstant

ApprovalFamilySchemaconstant

ApprovalScopeSchemaconstant

ApprovalRequesterSchemaconstant

ApprovalDescriptionSchemaconstant

PendingApprovalSchemaconstant

ApprovalStateSchemaconstant

ApprovalRefusalReasonSchemaconstant

MAX_APPROVAL_DENIAL_NOTE_LENGTHconstant

ApprovalDenialNoteSchemaconstant

MAX_APPROVAL_EVIDENCEconstant

MAX_APPROVAL_EVIDENCE_BYTESconstant

ApprovalEvidenceSchemaconstant

ApprovalRecordSchemaconstant

ApprovalViewSchemaconstant

ApprovalListInputSchemaconstant

ApprovalGetInputSchemaconstant

ApprovalAnswerInputSchemaconstant

AutoApproveInputSchemaconstant

ApprovalRefusalSchemaconstant

DEFAULT_APPROVAL_EXPIRY_MSconstant

denialFeedbackOpening()function