@fungi.computer/shiitake-extensions 0.4.0 → 0.5.0

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"`; \}\>

package/docs/api/subagents/host.md

@@ -78,7 +78,6 @@ stops the Agent's work.
 type SubagentTiming = Readonly<{
   refreshMs: number;
   pollMs: number;
-  interestMs: number;
 }>;
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/shiitake-extensions",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": "Levi <levi@technomancy.dev>",
   "private": false,
   "description": "Botanical's product Shiitake extensions: goal, loop and Almanac on the generic extension surface",
@@ -46,6 +46,10 @@
       "types": "./dist/roster.d.ts",
       "import": "./dist/roster.js"
     },
+    "./schedules": {
+      "types": "./dist/schedules.d.ts",
+      "import": "./dist/schedules.js"
+    },
     "./roster/conversation-agents": {
       "types": "./dist/roster/conversation-agents.d.ts",
       "import": "./dist/roster/conversation-agents.js"
@@ -108,9 +112,9 @@
   "dependencies": {
     "@fungi.computer/almanac": "0.2.0",
     "@fungi.computer/cairn": "0.1.0",
-    "@fungi.computer/knapsack": "0.4.0",
-    "@fungi.computer/mycelium": "0.2.3",
-    "@fungi.computer/shiitake": "0.6.0",
+    "@fungi.computer/knapsack": "0.4.1",
+    "@fungi.computer/mycelium": "0.3.0",
+    "@fungi.computer/shiitake": "0.7.0",
     "@fungi.computer/watchdog": "0.1.0",
     "@fungi.computer/whistle": "0.3.0",
     "effect": "4.0.2",