@fungi.computer/shiitake-extensions 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.md +15 -1
  2. package/dist/almanac/contract.d.ts +1 -107
  3. package/dist/almanac/contract.js +4 -40
  4. package/dist/almanac/schema.d.ts +41 -0
  5. package/dist/almanac/schema.js +40 -0
  6. package/dist/internal/schedule-fields.d.ts +5 -0
  7. package/dist/internal/schedule-fields.js +5 -0
  8. package/dist/loop/contract.d.ts +31 -185
  9. package/dist/loop/contract.js +13 -48
  10. package/dist/loop/host.js +4 -1
  11. package/dist/loop/schema.d.ts +49 -0
  12. package/dist/loop/schema.js +49 -0
  13. package/dist/schedules/client.d.ts +16 -0
  14. package/dist/schedules/client.js +81 -0
  15. package/dist/schedules.d.ts +1 -15
  16. package/dist/schedules.js +8 -83
  17. package/docs/api/README.md +1 -0
  18. package/docs/api/almanac/contract.md +46 -46
  19. package/docs/api/loop/contract.md +50 -46
  20. package/docs/api/roster/conversation-agents.md +22 -0
  21. package/docs/api/schedules/client.md +228 -0
  22. package/docs/api/schedules.md +0 -219
  23. package/package.json +8 -4
package/docs/api/schedules/client.md ADDED
@@ -0,0 +1,228 @@
1
+ <!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
2
+
3
+ [**@fungi.computer/shiitake-extensions**](../README.md)
4
+
5
+ ---
6
+
7
+ [@fungi.computer/shiitake-extensions](../README.md) / schedules/client
8
+
9
+ # schedules/client
10
+
11
+ ## Functions
12
+
13
+ ### readAgentSchedulePage()
14
+
15
+ ```ts
16
+ function readAgentSchedulePage(
17
+ agentId,
18
+ owner,
19
+ input?,
20
+ ): Promise<{
21
+ items: readonly (
22
+ | {
23
+ agentId: string;
24
+ kind: "almanac";
25
+ schedule: {
26
+ id: string;
27
+ sessionId: string;
28
+ prompt: string;
29
+ cron: {
30
+ expression: string;
31
+ timeZone: string;
32
+ } | null;
33
+ nextDueAt: number;
34
+ state: "active" | "paused" | "cancelled" | "finished";
35
+ lastCommandId: string | null;
36
+ lastError: string | null;
37
+ attempt: number;
38
+ };
39
+ }
40
+ | {
41
+ agentId: string;
42
+ kind: "loop";
43
+ schedule: {
44
+ loopId: string;
45
+ origin: "human" | "model";
46
+ expiresAt: number | null;
47
+ prompt: string;
48
+ mode: "self_paced" | "fixed_interval";
49
+ cron: {
50
+ expression: string;
51
+ timeZone: string;
52
+ } | null;
53
+ state: "active" | "paused" | "cancelled" | "finished" | "failed";
54
+ commandId: string;
55
+ reason: string | null;
56
+ nextDueAt: number | null;
57
+ lastError: string | null;
58
+ consecutiveFailures: number;
59
+ sessionId: string;
60
+ };
61
+ }
62
+ )[];
63
+ next: {
64
+ agentId: string;
65
+ kind: "loop" | "almanac";
66
+ after?: string;
67
+ } | null;
68
+ }>;
69
+ ```
70
+
71
+ Read one already-admitted Agent, without scanning Sessions or draining pages.
72
+ The caller owns Agent, home and resource authorization and the owner's lifetime.
73
+
74
+ #### Parameters
75
+
76
+ | Parameter | Type | Description |
77
+ | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
78
+ | `agentId` | `string` | - |
79
+ | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> | - |
80
+ | `input` | \{ `after?`: \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \}; `limit?`: `number`; \} | - |
81
+ | `input.after?` | \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \} | Native continuation from the previous page of this Agent's schedules. |
82
+ | `input.after.agentId` | `string` | Agent whose retained schedules this continuation traverses. |
83
+ | `input.after.kind` | `"loop"` \| `"almanac"` | Native owner to continue; Almanac precedes Loop in a fresh traversal. |
84
+ | `input.after.after?` | `string` | Exclusive Almanac schedule ID or Loop Session ID; absent starts the kind. |
85
+ | `input.limit?` | `number` | Shared row budget across both native kinds; defaults to and cannot exceed 64. |
86
+
87
+ #### Returns
88
+
89
+ `Promise`\<\{ `items`: readonly ( \| \{ `agentId`: `string`; `kind`:
90
+ `"almanac"`; `schedule`: \{ `id`: `string`; `sessionId`: `string`; `prompt`:
91
+ `string`; `cron`: \| \{ `expression`: `string`; `timeZone`: `string`; \} \|
92
+ `null`; `nextDueAt`: `number`; `state`: `"active"` \| `"paused"` \|
93
+ `"cancelled"` \| `"finished"`; `lastCommandId`: `string` \| `null`; `lastError`:
94
+ `string` \| `null`; `attempt`: `number`; \}; \} \| \{ `agentId`: `string`;
95
+ `kind`: `"loop"`; `schedule`: \{ `loopId`: `string`; `origin`: `"human"` \|
96
+ `"model"`; `expiresAt`: `number` \| `null`; `prompt`: `string`; `mode`:
97
+ `"self_paced"` \| `"fixed_interval"`; `cron`: \| \{ `expression`: `string`;
98
+ `timeZone`: `string`; \} \| `null`; `state`: `"active"` \| `"paused"` \|
99
+ `"cancelled"` \| `"finished"` \| `"failed"`; `commandId`: `string`; `reason`:
100
+ `string` \| `null`; `nextDueAt`: `number` \| `null`; `lastError`: `string` \|
101
+ `null`; `consecutiveFailures`: `number`; `sessionId`: `string`; \}; \})[];
102
+ `next`: \| \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`:
103
+ `string`; \} \| `null`; \}\>
104
+
105
+ ---
106
+
107
+ ### controlAgentScheduleWithContent()
108
+
109
+ ```ts
110
+ function controlAgentScheduleWithContent(
111
+ owner,
112
+ input,
113
+ action,
114
+ ): Promise<
115
+ | {
116
+ agentId: string;
117
+ kind: "almanac";
118
+ schedule: {
119
+ id: string;
120
+ sessionId: string;
121
+ prompt: string;
122
+ cron: {
123
+ expression: string;
124
+ timeZone: string;
125
+ } | null;
126
+ nextDueAt: number;
127
+ state: "active" | "paused" | "cancelled" | "finished";
128
+ lastCommandId: string | null;
129
+ lastError: string | null;
130
+ attempt: number;
131
+ };
132
+ }
133
+ | {
134
+ agentId: string;
135
+ kind: "loop";
136
+ schedule: {
137
+ loopId: string;
138
+ origin: "human" | "model";
139
+ expiresAt: number | null;
140
+ prompt: string;
141
+ mode: "self_paced" | "fixed_interval";
142
+ cron: {
143
+ expression: string;
144
+ timeZone: string;
145
+ } | null;
146
+ state: "active" | "paused" | "cancelled" | "finished" | "failed";
147
+ commandId: string;
148
+ reason: string | null;
149
+ nextDueAt: number | null;
150
+ lastError: string | null;
151
+ consecutiveFailures: number;
152
+ sessionId: string;
153
+ };
154
+ }
155
+ >;
156
+ ```
157
+
158
+ Explicit content-returning control for callers admitted to both read and manage.
159
+ In particular, private Local retains its native-row reply. The supplied owner
160
+ must already be admitted for target.agentId; this helper grants no authority.
161
+
162
+ #### Parameters
163
+
164
+ | Parameter | Type |
165
+ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166
+ | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> |
167
+ | `input` | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
168
+ | `action` | `"pause"` \| `"resume"` \| `"delete"` |
169
+
170
+ #### Returns
171
+
172
+ `Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `schedule`: \{ `id`:
173
+ `string`; `sessionId`: `string`; `prompt`: `string`; `cron`: \| \{ `expression`:
174
+ `string`; `timeZone`: `string`; \} \| `null`; `nextDueAt`: `number`; `state`:
175
+ `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; `lastCommandId`:
176
+ `string` \| `null`; `lastError`: `string` \| `null`; `attempt`: `number`; \}; \}
177
+ \| \{ `agentId`: `string`; `kind`: `"loop"`; `schedule`: \{ `loopId`: `string`;
178
+ `origin`: `"human"` \| `"model"`; `expiresAt`: `number` \| `null`; `prompt`:
179
+ `string`; `mode`: `"self_paced"` \| `"fixed_interval"`; `cron`: \| \{
180
+ `expression`: `string`; `timeZone`: `string`; \} \| `null`; `state`: `"active"`
181
+ \| `"paused"` \| `"cancelled"` \| `"finished"` \| `"failed"`; `commandId`:
182
+ `string`; `reason`: `string` \| `null`; `nextDueAt`: `number` \| `null`;
183
+ `lastError`: `string` \| `null`; `consecutiveFailures`: `number`; `sessionId`:
184
+ `string`; \}; \}\>
185
+
186
+ ---
187
+
188
+ ### controlAgentSchedule()
189
+
190
+ ```ts
191
+ function controlAgentSchedule(
192
+ owner,
193
+ target,
194
+ action,
195
+ ): Promise<
196
+ | {
197
+ agentId: string;
198
+ kind: "almanac";
199
+ scheduleId: string;
200
+ state: "active" | "paused" | "cancelled" | "finished";
201
+ }
202
+ | {
203
+ agentId: string;
204
+ kind: "loop";
205
+ sessionId: string;
206
+ loopId: string;
207
+ state: "active" | "paused" | "cancelled" | "finished" | "failed";
208
+ }
209
+ >;
210
+ ```
211
+
212
+ Control an already-admitted owner; manage-only callers receive no read content.
213
+
214
+ #### Parameters
215
+
216
+ | Parameter | Type |
217
+ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
+ | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> |
219
+ | `target` | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
220
+ | `action` | `"pause"` \| `"resume"` \| `"delete"` |
221
+
222
+ #### Returns
223
+
224
+ `Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `scheduleId`:
225
+ `string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; \}
226
+ \| \{ `agentId`: `string`; `kind`: `"loop"`; `sessionId`: `string`; `loopId`:
227
+ `string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"` \|
228
+ `"failed"`; \}\>
package/docs/api/schedules.md CHANGED
@@ -260,222 +260,3 @@ const agentScheduleControlReceiptSchema: Union<
260
260
  ```
261
261
 
262
262
  Manage-only result: exact target and native state, never prompt or history.
263
-
264
- ## Functions
265
-
266
- ### readAgentSchedulePage()
267
-
268
- ```ts
269
- function readAgentSchedulePage(
270
- agentId,
271
- owner,
272
- input?,
273
- ): Promise<{
274
- items: readonly (
275
- | {
276
- agentId: string;
277
- kind: "almanac";
278
- schedule: {
279
- id: string;
280
- sessionId: string;
281
- prompt: string;
282
- cron: {
283
- expression: string;
284
- timeZone: string;
285
- } | null;
286
- nextDueAt: number;
287
- state: "active" | "paused" | "cancelled" | "finished";
288
- lastCommandId: string | null;
289
- lastError: string | null;
290
- attempt: number;
291
- };
292
- }
293
- | {
294
- agentId: string;
295
- kind: "loop";
296
- schedule: {
297
- loopId: string;
298
- origin: "human" | "model";
299
- expiresAt: number | null;
300
- prompt: string;
301
- mode: "self_paced" | "fixed_interval";
302
- cron: {
303
- expression: string;
304
- timeZone: string;
305
- } | null;
306
- state: "active" | "paused" | "cancelled" | "finished" | "failed";
307
- commandId: string;
308
- reason: string | null;
309
- nextDueAt: number | null;
310
- lastError: string | null;
311
- consecutiveFailures: number;
312
- sessionId: string;
313
- };
314
- }
315
- )[];
316
- next: {
317
- agentId: string;
318
- kind: "loop" | "almanac";
319
- after?: string;
320
- } | null;
321
- }>;
322
- ```
323
-
324
- Read one already-admitted Agent, without scanning Sessions or draining pages.
325
- The caller owns Agent, home and resource authorization and the owner's lifetime.
326
-
327
- #### Parameters
328
-
329
- | Parameter | Type | Description |
330
- | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
331
- | `agentId` | `string` | - |
332
- | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> | - |
333
- | `input` | \{ `after?`: \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \}; `limit?`: `number`; \} | - |
334
- | `input.after?` | \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`: `string`; \} | Native continuation from the previous page of this Agent's schedules. |
335
- | `input.after.agentId` | `string` | Agent whose retained schedules this continuation traverses. |
336
- | `input.after.kind` | `"loop"` \| `"almanac"` | Native owner to continue; Almanac precedes Loop in a fresh traversal. |
337
- | `input.after.after?` | `string` | Exclusive Almanac schedule ID or Loop Session ID; absent starts the kind. |
338
- | `input.limit?` | `number` | Shared row budget across both native kinds; defaults to and cannot exceed 64. |
339
-
340
- #### Returns
341
-
342
- `Promise`\<\{ `items`: readonly ( \| \{ `agentId`: `string`; `kind`:
343
- `"almanac"`; `schedule`: \{ `id`: `string`; `sessionId`: `string`; `prompt`:
344
- `string`; `cron`: \| \{ `expression`: `string`; `timeZone`: `string`; \} \|
345
- `null`; `nextDueAt`: `number`; `state`: `"active"` \| `"paused"` \|
346
- `"cancelled"` \| `"finished"`; `lastCommandId`: `string` \| `null`; `lastError`:
347
- `string` \| `null`; `attempt`: `number`; \}; \} \| \{ `agentId`: `string`;
348
- `kind`: `"loop"`; `schedule`: \{ `loopId`: `string`; `origin`: `"human"` \|
349
- `"model"`; `expiresAt`: `number` \| `null`; `prompt`: `string`; `mode`:
350
- `"self_paced"` \| `"fixed_interval"`; `cron`: \| \{ `expression`: `string`;
351
- `timeZone`: `string`; \} \| `null`; `state`: `"active"` \| `"paused"` \|
352
- `"cancelled"` \| `"finished"` \| `"failed"`; `commandId`: `string`; `reason`:
353
- `string` \| `null`; `nextDueAt`: `number` \| `null`; `lastError`: `string` \|
354
- `null`; `consecutiveFailures`: `number`; `sessionId`: `string`; \}; \})[];
355
- `next`: \| \{ `agentId`: `string`; `kind`: `"loop"` \| `"almanac"`; `after?`:
356
- `string`; \} \| `null`; \}\>
357
-
358
- ---
359
-
360
- ### controlAgentScheduleWithContent()
361
-
362
- ```ts
363
- function controlAgentScheduleWithContent(
364
- owner,
365
- input,
366
- action,
367
- ): Promise<
368
- | {
369
- agentId: string;
370
- kind: "almanac";
371
- schedule: {
372
- id: string;
373
- sessionId: string;
374
- prompt: string;
375
- cron: {
376
- expression: string;
377
- timeZone: string;
378
- } | null;
379
- nextDueAt: number;
380
- state: "active" | "paused" | "cancelled" | "finished";
381
- lastCommandId: string | null;
382
- lastError: string | null;
383
- attempt: number;
384
- };
385
- }
386
- | {
387
- agentId: string;
388
- kind: "loop";
389
- schedule: {
390
- loopId: string;
391
- origin: "human" | "model";
392
- expiresAt: number | null;
393
- prompt: string;
394
- mode: "self_paced" | "fixed_interval";
395
- cron: {
396
- expression: string;
397
- timeZone: string;
398
- } | null;
399
- state: "active" | "paused" | "cancelled" | "finished" | "failed";
400
- commandId: string;
401
- reason: string | null;
402
- nextDueAt: number | null;
403
- lastError: string | null;
404
- consecutiveFailures: number;
405
- sessionId: string;
406
- };
407
- }
408
- >;
409
- ```
410
-
411
- Explicit content-returning control for callers admitted to both read and manage.
412
- In particular, private Local retains its native-row reply. The supplied owner
413
- must already be admitted for target.agentId; this helper grants no authority.
414
-
415
- #### Parameters
416
-
417
- | Parameter | Type |
418
- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
419
- | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> |
420
- | `input` | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
421
- | `action` | `"pause"` \| `"delete"` |
422
-
423
- #### Returns
424
-
425
- `Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `schedule`: \{ `id`:
426
- `string`; `sessionId`: `string`; `prompt`: `string`; `cron`: \| \{ `expression`:
427
- `string`; `timeZone`: `string`; \} \| `null`; `nextDueAt`: `number`; `state`:
428
- `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; `lastCommandId`:
429
- `string` \| `null`; `lastError`: `string` \| `null`; `attempt`: `number`; \}; \}
430
- \| \{ `agentId`: `string`; `kind`: `"loop"`; `schedule`: \{ `loopId`: `string`;
431
- `origin`: `"human"` \| `"model"`; `expiresAt`: `number` \| `null`; `prompt`:
432
- `string`; `mode`: `"self_paced"` \| `"fixed_interval"`; `cron`: \| \{
433
- `expression`: `string`; `timeZone`: `string`; \} \| `null`; `state`: `"active"`
434
- \| `"paused"` \| `"cancelled"` \| `"finished"` \| `"failed"`; `commandId`:
435
- `string`; `reason`: `string` \| `null`; `nextDueAt`: `number` \| `null`;
436
- `lastError`: `string` \| `null`; `consecutiveFailures`: `number`; `sessionId`:
437
- `string`; \}; \}\>
438
-
439
- ---
440
-
441
- ### controlAgentSchedule()
442
-
443
- ```ts
444
- function controlAgentSchedule(
445
- owner,
446
- target,
447
- action,
448
- ): Promise<
449
- | {
450
- agentId: string;
451
- kind: "almanac";
452
- scheduleId: string;
453
- state: "active" | "paused" | "cancelled" | "finished";
454
- }
455
- | {
456
- agentId: string;
457
- kind: "loop";
458
- sessionId: string;
459
- loopId: string;
460
- state: "active" | "paused" | "cancelled" | "finished" | "failed";
461
- }
462
- >;
463
- ```
464
-
465
- Control an already-admitted owner; manage-only callers receive no read content.
466
-
467
- #### Parameters
468
-
469
- | Parameter | Type |
470
- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
471
- | `owner` | `Pick`\<`ShiitakeAgent`, `"extensions"`\> |
472
- | `target` | \| \{ `kind`: `"almanac"`; `agentId`: `string`; `scheduleId`: `string`; \} \| \{ `kind`: `"loop"`; `agentId`: `string`; `sessionId`: `string`; `loopId`: `string`; \} |
473
- | `action` | `"pause"` \| `"delete"` |
474
-
475
- #### Returns
476
-
477
- `Promise`\< \| \{ `agentId`: `string`; `kind`: `"almanac"`; `scheduleId`:
478
- `string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"`; \}
479
- \| \{ `agentId`: `string`; `kind`: `"loop"`; `sessionId`: `string`; `loopId`:
480
- `string`; `state`: `"active"` \| `"paused"` \| `"cancelled"` \| `"finished"` \|
481
- `"failed"`; \}\>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fungi.computer/shiitake-extensions",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "author": "Levi <levi@technomancy.dev>",
5
5
  "private": false,
6
6
  "description": "Botanical's product Shiitake extensions: goal, loop and Almanac on the generic extension surface",
@@ -50,6 +50,10 @@
50
50
  "types": "./dist/schedules.d.ts",
51
51
  "import": "./dist/schedules.js"
52
52
  },
53
+ "./schedules/client": {
54
+ "types": "./dist/schedules/client.d.ts",
55
+ "import": "./dist/schedules/client.js"
56
+ },
53
57
  "./roster/conversation-agents": {
54
58
  "types": "./dist/roster/conversation-agents.d.ts",
55
59
  "import": "./dist/roster/conversation-agents.js"
@@ -112,9 +116,9 @@
112
116
  "dependencies": {
113
117
  "@fungi.computer/almanac": "0.2.0",
114
118
  "@fungi.computer/cairn": "0.1.0",
115
- "@fungi.computer/knapsack": "0.4.1",
116
- "@fungi.computer/mycelium": "0.3.0",
117
- "@fungi.computer/shiitake": "0.7.0",
119
+ "@fungi.computer/knapsack": "0.4.2",
120
+ "@fungi.computer/mycelium": "0.3.1",
121
+ "@fungi.computer/shiitake": "0.8.0",
118
122
  "@fungi.computer/watchdog": "0.1.0",
119
123
  "@fungi.computer/whistle": "0.3.0",
120
124
  "effect": "4.0.2",