@fungi.computer/shiitake-extensions 0.3.0 → 0.5.0

package/docs/api/question/host.md

@@ -16,4 +16,34 @@
 const questionExtension: RosteredExtensionV0;
 ```
 
+Hub's shared roster sends every Ask to a person.
+
+---
+
+### localQuestionExtension
+
+```ts
+const localQuestionExtension: RosteredExtensionV0;
+```
+
+Local's roster sends an Ask to the Agent that sent the asking work first.
+
+## Functions
+
+### questionExtensionFor()
+
+```ts
+function questionExtensionFor(routesToSender): RosteredExtensionV0;
+```
+
 One durable question owner over the ordinary extension doors.
+
+#### Parameters
+
+| Parameter        | Type      |
+| ---------------- | --------- |
+| `routesToSender` | `boolean` |
+
+#### Returns
+
+`RosteredExtensionV0`

package/docs/api/roster/conversation-agents.md

@@ -8,6 +8,24 @@
 
 # roster/conversation-agents
 
+## Type Aliases
+
+### SendingDirectory
+
+```ts
+type SendingDirectory = Omit<AgentControlDirectory, "open"> & Readonly<{
+  open: (agentId, signal) => Promise<Readonly<{
+     agent: Readonly<{
+        session: (sessionId) => Pick<..., ...>;
+     }>;
+     release: () => Promise<void>;
+  }>>;
+}>;
+```
+
+The directory a conversation sends through; opening a recipient only needs its
+Sessions' extension doors.
+
 ## Functions
 
 ### assertOrdinaryAgentCreation()
@@ -39,8 +57,10 @@ function createConversationAgents(storage): object;
 
 This host's own record of the Agents each conversation created or sent accepted
 work to, written as its Agent-control directory accepts them (Wiki:
-agent-runtime-tools-and-clients, read-only sub-agent view). It feeds the footer
-only; it owns no relationship and grants nothing.
+agent-runtime-tools-and-clients, read-only sub-agent view). Accepted child
+command receipts are separately reconciled against their owner's settlement
+records for the parent's goal guard. Neither record grants authority over a
+child.
 
 #### Parameters
 
@@ -52,7 +72,7 @@ only; it owns no relationship and grants nothing.
 
 | Name          | Type                                                                     | Description                                                                                                                                     |
 | ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `recording()` | (`parentSessionId`, `directory`) => `AgentControlDirectory`              | Bind acceptance recording to this conversation's existing directory. One conversation's directory: its accepted creates and sends are recorded. |
+| `recording()` | \<`Directory`\>(`parentSessionId`, `directory`) => `Directory`           | Bind acceptance recording to this conversation's existing directory. One conversation's directory: its accepted creates and sends are recorded. |
 | `control()`   | (`directoryFor`) => `CapabilitySource`                                   | Agent-control tools bound to the conversation that acquires them.                                                                               |
 | `source()`    | (`directory`) => [`SubagentSource`](../subagents/host.md#subagentsource) | The footer rows for one conversation; archived and unknown Agents leave it.                                                                     |
 
@@ -61,7 +81,14 @@ only; it owns no relationship and grants nothing.
 ### oysterAgentExtensions()
 
 ```ts
-function oysterAgentExtensions(source): object;
+function oysterAgentExtensions(source): Readonly<{
+  roster: readonly RosteredExtensionV0[];
+  grants: readonly Readonly<{
+    id: string & Brand<"ExtensionId">;
+    capabilities: readonly ExtensionCapabilityV0[];
+    grantKey?: string;
+  }>[];
+}>;
 ```
 
 Both hosts compose the ordinary roster and its read-only created-Agent footer.
@@ -74,7 +101,6 @@ Both hosts compose the ordinary roster and its read-only created-Agent footer.
 
 #### Returns
 
-| Name     | Type                                                                                                                                          | Description                                                  |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `roster` | `RosteredExtensionV0`[]                                                                                                                       | Ordinary extensions plus the read-only created-Agent footer. |
-| `grants` | `Readonly`\<\{ `id`: `string` & `Brand`\<`"ExtensionId"`\>; `capabilities`: readonly `ExtensionCapabilityV0`[]; `grantKey?`: `string`; \}\>[] | Host grants corresponding to the composed extension roster.  |
+`Readonly`\<\{ `roster`: readonly `RosteredExtensionV0`[]; `grants`: readonly
+`Readonly`\<\{ `id`: `string` & `Brand`\<`"ExtensionId"`\>; `capabilities`:
+readonly `ExtensionCapabilityV0`[]; `grantKey?`: `string`; \}\>[]; \}\>

package/docs/api/roster.md

@@ -16,11 +16,33 @@
 const botanicalAgentExtensions: ExtensionRosterV0;
 ```
 
-Botanical's product roster with explicit grants. Hub and Local pass this same
-value; a stranger host passes its own (or an empty) roster.
+Botanical's shared roster with explicit grants. Local composes its
+sender-routing question extension through `botanicalExtensionsWithSkills`; hosts
+without that Local capability send every Ask to a person.
 
 ## Functions
 
+### botanicalExtensionsWithSubagents()
+
+```ts
+function botanicalExtensionsWithSubagents(base, source): ExtensionRosterV0;
+```
+
+Compose the goal and footer over one source; an absent goal is a wiring error.
+
+#### Parameters
+
+| Parameter | Type                                                 |
+| --------- | ---------------------------------------------------- |
+| `base`    | `ExtensionRosterV0`                                  |
+| `source`  | [`SubagentSource`](subagents/host.md#subagentsource) |
+
+#### Returns
+
+`ExtensionRosterV0`
+
+---
+
 ### botanicalExtensionsWithSkills()
 
 ```ts
@@ -38,3 +60,18 @@ A host with a SkillSource grants read-only skill discovery for its own runs.
 #### Returns
 
 `ExtensionRosterV0`
+
+---
+
+### botanicalExtensionsWithSenderRouting()
+
+```ts
+function botanicalExtensionsWithSenderRouting(): ExtensionRosterV0;
+```
+
+Route Asks to the Agent that sent the work, only in a host that owns the Local
+answer door.
+
+#### Returns
+
+`ExtensionRosterV0`

package/docs/api/schedules.md

@@ -0,0 +1,481 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake-extensions**](README.md)
+
+---
+
+[@fungi.computer/shiitake-extensions](README.md) / schedules
+
+# schedules
+
+## Type Aliases
+
+### AgentScheduleRow
+
+```ts
+type AgentScheduleRow = typeof agentScheduleRowSchema.Type;
+```
+
+One Agent's retained schedule, including its native content.
+
+---
+
+### AgentScheduleTarget
+
+```ts
+type AgentScheduleTarget = z.output<typeof agentScheduleTargetSchema>;
+```
+
+Identity to admit before acquiring the corresponding Agent owner.
+
+---
+
+### AgentSchedulePage
+
+```ts
+type AgentSchedulePage = typeof agentSchedulePageSchema.Type;
+```
+
+One Agent's page, with no directory fan-out or availability policy.
+
+---
+
+### AgentScheduleControlReceipt
+
+```ts
+type AgentScheduleControlReceipt =
+  typeof agentScheduleControlReceiptSchema.Type;
+```
+
+Content-free acknowledgement of the native owner's completed transition.
+
+## Variables
+
+### agentScheduleCursorSchema
+
+```ts
+const agentScheduleCursorSchema: ZodObject<
+  {
+    agentId: ZodString;
+    kind: ZodUnion<readonly [ZodLiteral<"almanac">, ZodLiteral<"loop">]>;
+    after: ZodOptional<ZodString>;
+  },
+  $strict
+>;
+```
+
+Exclusive native key within one Agent's Almanac-then-Loop traversal.
+
+---
+
+### agentScheduleListInputSchema
+
+```ts
+const agentScheduleListInputSchema: ZodObject<
+  {
+    after: ZodOptional<
+      ZodObject<
+        {
+          agentId: ZodString;
+          kind: ZodUnion<readonly [ZodLiteral<"almanac">, ZodLiteral<"loop">]>;
+          after: ZodOptional<ZodString>;
+        },
+        $strict
+      >
+    >;
+    limit: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+One bounded read; a full native page conservatively carries continuation.
+
+---
+
+### agentScheduleRowSchema
+
+```ts
+const agentScheduleRowSchema: Union<
+  readonly [
+    Struct<{
+      agentId: String;
+      kind: Literal<"almanac">;
+      schedule: Struct<{
+        id: String;
+        sessionId: String;
+        prompt: String;
+        cron: NullOr<
+          Struct<{
+            expression: String;
+            timeZone: String;
+          }>
+        >;
+        nextDueAt: Int;
+        state: Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+        lastCommandId: NullOr<String>;
+        lastError: NullOr<String>;
+        attempt: Int;
+      }>;
+    }>,
+    Struct<{
+      agentId: String;
+      kind: Literal<"loop">;
+      schedule: Struct<{
+        loopId: String;
+        origin: Literals<readonly ["human", "model"]>;
+        expiresAt: NullOr<Int>;
+        prompt: String;
+        mode: Literals<readonly ["self_paced", "fixed_interval"]>;
+        cron: NullOr<
+          Struct<{
+            expression: String;
+            timeZone: String;
+          }>
+        >;
+        state: Literals<
+          readonly ["active", "paused", "finished", "failed", "cancelled"]
+        >;
+        commandId: String;
+        reason: NullOr<String>;
+        nextDueAt: NullOr<Int>;
+        lastError: NullOr<String>;
+        consecutiveFailures: Int;
+        sessionId: String;
+      }>;
+    }>,
+  ]
+>;
+```
+
+Content-bearing read projection, decoded by the retained native contracts.
+
+---
+
+### agentScheduleTargetSchema
+
+```ts
+const agentScheduleTargetSchema: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        kind: ZodLiteral<"almanac">;
+        agentId: ZodString;
+        scheduleId: ZodString &
+          ZodType<string, string, $ZodTypeInternals<string, string>>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        kind: ZodLiteral<"loop">;
+        agentId: ZodString;
+        sessionId: ZodString &
+          ZodType<string, string, $ZodTypeInternals<string, string>>;
+        loopId: ZodString &
+          ZodType<string, string, $ZodTypeInternals<string, string>>;
+      },
+      $strict
+    >,
+  ],
+  "kind"
+>;
+```
+
+Exact listed identity; a Loop target never selects its later replacement.
+
+---
+
+### agentSchedulePageSchema
+
+```ts
+const agentSchedulePageSchema: Struct<{
+  items: $Array<Union<readonly [Struct<{
+     agentId: String;
+     kind: Literal<"almanac">;
+     schedule: Struct<{
+        id: String;
+        sessionId: String;
+        prompt: String;
+        cron: NullOr<Struct<...>>;
+        nextDueAt: Int;
+        state: Literals<readonly [..., ..., ..., ...]>;
+        lastCommandId: NullOr<String>;
+        lastError: NullOr<String>;
+        attempt: Int;
+     }>;
+   }>, Struct<{
+     agentId: String;
+     kind: Literal<"loop">;
+     schedule: Struct<{
+        loopId: String;
+        origin: Literals<readonly [..., ...]>;
+        expiresAt: NullOr<Int>;
+        prompt: String;
+        mode: Literals<readonly [..., ...]>;
+        cron: NullOr<Struct<...>>;
+        state: Literals<readonly [..., ..., ..., ..., ...]>;
+        commandId: String;
+        reason: NullOr<String>;
+        nextDueAt: NullOr<Int>;
+        lastError: NullOr<String>;
+        consecutiveFailures: Int;
+        sessionId: String;
+     }>;
+  }>]>>;
+  next: NullOr<Struct<{
+     agentId: String;
+     kind: Literals<readonly ["almanac", "loop"]>;
+     after: optionalKey<String>;
+  }>>;
+}>;
+```
+
+A bounded content-bearing page; owner failures reject rather than look empty.
+
+---
+
+### agentScheduleControlReceiptSchema
+
+```ts
+const agentScheduleControlReceiptSchema: Union<
+  readonly [
+    Struct<{
+      agentId: String;
+      kind: Literal<"almanac">;
+      scheduleId: String;
+      state: Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+    }>,
+    Struct<{
+      agentId: String;
+      kind: Literal<"loop">;
+      sessionId: String;
+      loopId: String;
+      state: Literals<
+        readonly ["active", "paused", "finished", "failed", "cancelled"]
+      >;
+    }>,
+  ]
+>;
+```
+
+Manage-only result: exact target and native state, never prompt or history.
+
+## Functions
+
+### readAgentSchedulePage()
+
+```ts
+function readAgentSchedulePage(
+  agentId,
+  owner,
+  input?,
+): Promise<{
+  items: readonly (
+    | {
+        agentId: string;
+        kind: "almanac";
+        schedule: {
+          id: string;
+          sessionId: string;
+          prompt: string;
+          cron: {
+            expression: string;
+            timeZone: string;
+          } | null;
+          nextDueAt: number;
+          state: "active" | "paused" | "cancelled" | "finished";
+          lastCommandId: string | null;
+          lastError: string | null;
+          attempt: number;
+        };
+      }
+    | {
+        agentId: string;
+        kind: "loop";
+        schedule: {
+          loopId: string;
+          origin: "human" | "model";
+          expiresAt: number | null;
+          prompt: string;
+          mode: "self_paced" | "fixed_interval";
+          cron: {
+            expression: string;
+            timeZone: string;
+          } | null;
+          state: "active" | "paused" | "cancelled" | "finished" | "failed";
+          commandId: string;
+          reason: string | null;
+          nextDueAt: number | null;
+          lastError: string | null;
+          consecutiveFailures: number;
+          sessionId: string;
+        };
+      }
+  )[];
+  next: {
+    agentId: string;
+    kind: "loop" | "almanac";
+    after?: string;
+  } | null;
+}>;
+```
+
+Read one already-admitted Agent, without scanning Sessions or draining pages.
+The caller owns Agent, home and resource authorization and the owner's lifetime.
+
+#### Parameters
+
+| Parameter             | Type                                                                                                                 | Description                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `agentId`             | `string`                                                                                                             | -                                                                             |
+| `owner`               | `Pick`\<`ShiitakeAgent`, `"extensions"`\>                                                                            | -                                                                             |
+| `input`               | \{ `after?`: \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \}; `limit?`: `number`; \} | -                                                                             |
+| `input.after?`        | \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \}                                      | Native continuation from the previous page of this Agent's schedules.         |
+| `input.after.agentId` | `string`                                                                                                             | Agent whose retained schedules this continuation traverses.                   |
+| `input.after.kind`    | `"loop"` \| `"almanac"`                                                                                              | Native owner to continue; Almanac precedes Loop in a fresh traversal.         |
+| `input.after.after?`  | `string`                                                                                                             | Exclusive Almanac schedule ID or Loop Session ID; absent starts the kind.     |
+| `input.limit?`        | `number`                                                                                                             | Shared row budget across both native kinds; defaults to and cannot exceed 64. |
+
+#### Returns
+
+`Promise`\<\{ `items`: readonly ( \| \{ `agentId`: `string`; `kind`:
+`"almanac"`; `schedule`: \{ `id`: `string`; `sessionId`: `string`; `prompt`:
+`string`; `cron`: \| \{ `expression`: `string`; `timeZone`: `string`; \} \|
+`null`; `nextDueAt`: `number`; `state`: `"active"` \| `"paused"` \|
+`"cancelled"` \| `"finished"`; `lastCommandId`: `string` \| `null`; `lastError`:
+`string` \| `null`; `attempt`: `number`; \}; \} \| \{ `agentId`: `string`;
+`kind`: `"loop"`; `schedule`: \{ `loopId`: `string`; `origin`: `"human"` \|
+`"model"`; `expiresAt`: `number` \| `null`; `prompt`: `string`; `mode`:
+`"self_paced"` \| `"fixed_interval"`; `cron`: \| \{ `expression`: `string`;
+`timeZone`: `string`; \} \| `null`; `state`: `"active"` \| `"paused"` \|
+`"cancelled"` \| `"finished"` \| `"failed"`; `commandId`: `string`; `reason`:
+`string` \| `null`; `nextDueAt`: `number` \| `null`; `lastError`: `string` \|
+`null`; `consecutiveFailures`: `number`; `sessionId`: `string`; \}; \})[];
+`next`: \| \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`:
+`string`; \} \| `null`; \}\>
+
+---
+
+### controlAgentScheduleWithContent()
+
+```ts
+function controlAgentScheduleWithContent(
+  owner,
+  input,
+  action,
+): Promise<
+  | {
+      agentId: string;
+      kind: "almanac";
+      schedule: {
+        id: string;
+        sessionId: string;
+        prompt: string;
+        cron: {
+          expression: string;
+          timeZone: string;
+        } | null;
+        nextDueAt: number;
+        state: "active" | "paused" | "cancelled" | "finished";
+        lastCommandId: string | null;
+        lastError: string | null;
+        attempt: number;
+      };
+    }
+  | {
+      agentId: string;
+      kind: "loop";
+      schedule: {
+        loopId: string;
+        origin: "human" | "model";
+        expiresAt: number | null;
+        prompt: string;
+        mode: "self_paced" | "fixed_interval";
+        cron: {
+          expression: string;
+          timeZone: string;
+        } | null;
+        state: "active" | "paused" | "cancelled" | "finished" | "failed";
+        commandId: string;
+        reason: string | null;
+        nextDueAt: number | null;
+        lastError: string | null;
+        consecutiveFailures: number;
+        sessionId: string;
+      };
+    }
+>;
+```
+
+Explicit content-returning control for callers admitted to both read and manage.
+In particular, private Local retains its native-row reply. The supplied owner
+must already be admitted for target.agentId; this helper grants no authority.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                  |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `Pick`\<`ShiitakeAgent`, `"extensions"`\>                                                                                                                             |
+| `input`   | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
+| `action`  | `"pause"` \| `"delete"`                                                                                                                                               |
+
+#### Returns
+
+`Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `schedule`: \{ `id`:
+`string`; `sessionId`: `string`; `prompt`: `string`; `cron`: \| \{ `expression`:
+`string`; `timeZone`: `string`; \} \| `null`; `nextDueAt`: `number`; `state`:
+`"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; `lastCommandId`:
+`string` \| `null`; `lastError`: `string` \| `null`; `attempt`: `number`; \}; \}
+\| \{ `agentId`: `string`; `kind`: `"loop"`; `schedule`: \{ `loopId`: `string`;
+`origin`: `"human"` \| `"model"`; `expiresAt`: `number` \| `null`; `prompt`:
+`string`; `mode`: `"self_paced"` \| `"fixed_interval"`; `cron`: \| \{
+`expression`: `string`; `timeZone`: `string`; \} \| `null`; `state`: `"active"`
+\| `"paused"` \| `"cancelled"` \| `"finished"` \| `"failed"`; `commandId`:
+`string`; `reason`: `string` \| `null`; `nextDueAt`: `number` \| `null`;
+`lastError`: `string` \| `null`; `consecutiveFailures`: `number`; `sessionId`:
+`string`; \}; \}\>
+
+---
+
+### controlAgentSchedule()
+
+```ts
+function controlAgentSchedule(
+  owner,
+  target,
+  action,
+): Promise<
+  | {
+      agentId: string;
+      kind: "almanac";
+      scheduleId: string;
+      state: "active" | "paused" | "cancelled" | "finished";
+    }
+  | {
+      agentId: string;
+      kind: "loop";
+      sessionId: string;
+      loopId: string;
+      state: "active" | "paused" | "cancelled" | "finished" | "failed";
+    }
+>;
+```
+
+Control an already-admitted owner; manage-only callers receive no read content.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                  |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `Pick`\<`ShiitakeAgent`, `"extensions"`\>                                                                                                                             |
+| `target`  | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
+| `action`  | `"pause"` \| `"delete"`                                                                                                                                               |
+
+#### Returns
+
+`Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `scheduleId`:
+`string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; \}
+\| \{ `agentId`: `string`; `kind`: `"loop"`; `sessionId`: `string`; `loopId`:
+`string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"` \|
+`"failed"`; \}\>