@fungi.computer/shiitake-extensions 0.4.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.
- package/README.md +17 -4
- package/dist/almanac/contract.d.ts +1 -107
- package/dist/almanac/contract.js +4 -40
- package/dist/almanac/schema.d.ts +41 -0
- package/dist/almanac/schema.js +40 -0
- package/dist/goal/host.js +3 -1
- package/dist/internal/schedule-fields.d.ts +5 -0
- package/dist/internal/schedule-fields.js +5 -0
- package/dist/loop/contract.d.ts +123 -143
- package/dist/loop/contract.js +51 -43
- package/dist/loop/host.js +26 -0
- package/dist/loop/schema.d.ts +49 -0
- package/dist/loop/schema.js +49 -0
- package/dist/roster/conversation-agents.d.ts +11 -2
- package/dist/roster/conversation-agents.js +16 -6
- package/dist/schedules/client.d.ts +16 -0
- package/dist/schedules/client.js +81 -0
- package/dist/schedules.d.ts +164 -0
- package/dist/schedules.js +107 -0
- package/docs/api/README.md +2 -0
- package/docs/api/almanac/contract.md +46 -46
- package/docs/api/goal/contract.md +1 -1
- package/docs/api/loop/contract.md +90 -74
- package/docs/api/roster/conversation-agents.md +41 -1
- package/docs/api/schedules/client.md +228 -0
- package/docs/api/schedules.md +262 -0
- package/docs/api/subagents/host.md +0 -1
- package/package.json +12 -4
|
@@ -20,6 +20,52 @@ One durable schedule.
|
|
|
20
20
|
|
|
21
21
|
## Variables
|
|
22
22
|
|
|
23
|
+
### almanacContract
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const almanacContract: object;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Almanac's contract: agent-scope schedule CRUD, no Session projection.
|
|
30
|
+
|
|
31
|
+
#### Type Declaration
|
|
32
|
+
|
|
33
|
+
| Name | Type | Default value | Description |
|
|
34
|
+
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------ |
|
|
35
|
+
| <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity. |
|
|
36
|
+
| <a id="property-commands"></a> `commands` | `object` | - | Agent-scoped schedule operations. |
|
|
37
|
+
| `commands.createOneShot` | `object` | - | Create a schedule with one due occurrence. |
|
|
38
|
+
| `commands.createOneShot.scope` | `"agent"` | `"agent"` | The Agent owns the schedule collection. |
|
|
39
|
+
| `commands.createOneShot.input` | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `dueAt`: `Int`; \}\> | - | Decode the caller's one-shot schedule request. |
|
|
40
|
+
| `commands.createOneShot.output` | `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`; \}\> | `Schedule` | Return the created durable schedule. |
|
|
41
|
+
| `commands.createRecurring` | `object` | - | Create a recurring cron schedule. |
|
|
42
|
+
| `commands.createRecurring.scope` | `"agent"` | `"agent"` | The Agent owns the schedule collection. |
|
|
43
|
+
| `commands.createRecurring.input` | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `expression`: `String`; `timeZone`: `String`; \}\> | - | Decode the caller's recurring schedule request. |
|
|
44
|
+
| `commands.createRecurring.output` | `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`; \}\> | `Schedule` | Return the created durable schedule. |
|
|
45
|
+
| `commands.read` | `object` | - | Read one schedule, or null when absent. |
|
|
46
|
+
| `commands.read.scope` | `"agent"` | `"agent"` | Read from the Agent's schedule collection. |
|
|
47
|
+
| `commands.read.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to read. |
|
|
48
|
+
| `commands.read.output` | `NullOr`\<`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`; \}\>\> | - | Decode the schedule or its absence. |
|
|
49
|
+
| `commands.list` | `object` | - | Read a bounded page of schedules after an optional identity. |
|
|
50
|
+
| `commands.list.scope` | `"agent"` | `"agent"` | Read from the Agent's schedule collection. |
|
|
51
|
+
| `commands.list.input` | `Struct`\<\{ `after`: `optionalKey`\<`String`\>; `limit`: `optionalKey`\<`Int`\>; \}\> | `ScheduleListInput` | Decode pagination arguments. |
|
|
52
|
+
| `commands.list.output` | `$Array`\<`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`; \}\>\> | - | Decode the returned schedule rows. |
|
|
53
|
+
| `commands.pause` | `object` | - | Suspend future occurrences of a schedule. |
|
|
54
|
+
| `commands.pause.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
55
|
+
| `commands.pause.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to pause. |
|
|
56
|
+
| `commands.pause.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
57
|
+
| `commands.resume` | `object` | - | Restore a paused schedule to active scheduling. |
|
|
58
|
+
| `commands.resume.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
59
|
+
| `commands.resume.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to resume. |
|
|
60
|
+
| `commands.resume.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
61
|
+
| `commands.cancel` | `object` | - | Cancel future occurrences of a schedule. |
|
|
62
|
+
| `commands.cancel.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
63
|
+
| `commands.cancel.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to cancel. |
|
|
64
|
+
| `commands.cancel.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
65
|
+
| <a id="property-projection"></a> `projection` | `null` | `null` | Almanac has no Session projection. |
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
23
69
|
### Schedule
|
|
24
70
|
|
|
25
71
|
```ts
|
|
@@ -42,49 +88,3 @@ const Schedule: Struct<{
|
|
|
42
88
|
```
|
|
43
89
|
|
|
44
90
|
One durable schedule as every caller sees it.
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
### almanacContract
|
|
49
|
-
|
|
50
|
-
```ts
|
|
51
|
-
const almanacContract: object;
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Almanac's contract: agent-scope schedule CRUD, no Session projection.
|
|
55
|
-
|
|
56
|
-
#### Type Declaration
|
|
57
|
-
|
|
58
|
-
| Name | Type | Default value | Description |
|
|
59
|
-
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------ |
|
|
60
|
-
| <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity. |
|
|
61
|
-
| <a id="property-commands"></a> `commands` | `object` | - | Agent-scoped schedule operations. |
|
|
62
|
-
| `commands.createOneShot` | `object` | - | Create a schedule with one due occurrence. |
|
|
63
|
-
| `commands.createOneShot.scope` | `"agent"` | `"agent"` | The Agent owns the schedule collection. |
|
|
64
|
-
| `commands.createOneShot.input` | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `dueAt`: `Int`; \}\> | - | Decode the caller's one-shot schedule request. |
|
|
65
|
-
| `commands.createOneShot.output` | `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`; \}\> | `Schedule` | Return the created durable schedule. |
|
|
66
|
-
| `commands.createRecurring` | `object` | - | Create a recurring cron schedule. |
|
|
67
|
-
| `commands.createRecurring.scope` | `"agent"` | `"agent"` | The Agent owns the schedule collection. |
|
|
68
|
-
| `commands.createRecurring.input` | `Struct`\<\{ `requestId`: `String`; `sessionId`: `String`; `prompt`: `String`; `expression`: `String`; `timeZone`: `String`; \}\> | - | Decode the caller's recurring schedule request. |
|
|
69
|
-
| `commands.createRecurring.output` | `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`; \}\> | `Schedule` | Return the created durable schedule. |
|
|
70
|
-
| `commands.read` | `object` | - | Read one schedule, or null when absent. |
|
|
71
|
-
| `commands.read.scope` | `"agent"` | `"agent"` | Read from the Agent's schedule collection. |
|
|
72
|
-
| `commands.read.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to read. |
|
|
73
|
-
| `commands.read.output` | `NullOr`\<`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`; \}\>\> | - | Decode the schedule or its absence. |
|
|
74
|
-
| `commands.list` | `object` | - | Read a bounded page of schedules after an optional identity. |
|
|
75
|
-
| `commands.list.scope` | `"agent"` | `"agent"` | Read from the Agent's schedule collection. |
|
|
76
|
-
| `commands.list.input` | `Struct`\<\{ `after`: `optionalKey`\<`String`\>; `limit`: `optionalKey`\<`Int`\>; \}\> | - | Decode pagination arguments. |
|
|
77
|
-
| `commands.list.output` | `$Array`\<`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`; \}\>\> | - | Decode the returned schedule rows. |
|
|
78
|
-
| `commands.pause` | `object` | - | Suspend future occurrences of a schedule. |
|
|
79
|
-
| `commands.pause.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
80
|
-
| `commands.pause.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to pause. |
|
|
81
|
-
| `commands.pause.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
82
|
-
| `commands.resume` | `object` | - | Restore a paused schedule to active scheduling. |
|
|
83
|
-
| `commands.resume.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
84
|
-
| `commands.resume.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to resume. |
|
|
85
|
-
| `commands.resume.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
86
|
-
| `commands.cancel` | `object` | - | Cancel future occurrences of a schedule. |
|
|
87
|
-
| `commands.cancel.scope` | `"agent"` | `"agent"` | The Agent owns the schedule. |
|
|
88
|
-
| `commands.cancel.input` | `Struct`\<\{ `scheduleId`: `String`; \}\> | `ScheduleRef` | Identify the schedule to cancel. |
|
|
89
|
-
| `commands.cancel.output` | `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`; \}\> | `Schedule` | Return its updated state. |
|
|
90
|
-
| <a id="property-projection"></a> `projection` | `null` | `null` | Almanac has no Session projection. |
|
|
@@ -244,7 +244,7 @@ Session-owned goal controls and their visible projection.
|
|
|
244
244
|
| `commands.clear.output` | `Struct`\<\{ \}\> | - | A successful clear has no result fields. |
|
|
245
245
|
| `commands.set` | `object` | - | Set an objective against the revision the person saw. |
|
|
246
246
|
| `commands.set.scope` | `"session"` | `"session"` | The Session owns this goal. |
|
|
247
|
-
| `commands.set.input` | `Struct`\<\{ `objective`: `String`; `expectedRevision`: `NullOr`\<`String`\>; `requestId`: `String`; \}\>
|
|
247
|
+
| `commands.set.input` | `Struct`\<\{ `objective`: `String`; `expectedRevision`: `NullOr`\<`String`\>; `requestId`: `String`; `adoptCommandId`: `optionalKey`\<`String`\>; \}\> | - | Decode the new objective and replacement fence. |
|
|
248
248
|
| `commands.set.output` | `Struct`\<\{ `goal`: `Struct`\<\{ `revision`: `String`; `objective`: `String`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`\]\>; `startedAt`: `Int`; `pauseCause`: `NullOr`\<`Struct`\<\{ `kind`: `Literals`\<...\>; `detail`: `NullOr`\<...\>; \}\>\>; \}\>; `accepted`: `Struct`\<\{ `status`: `Literal`\<`"accepted"`\>; `commandId`: `String`; \}\>; \}\> | - | Return the goal and its admission receipt. |
|
|
249
249
|
| <a id="property-projection"></a> `projection` | `object` | - | Current and ended goals visible to clients. |
|
|
250
250
|
| `projection.schema` | `Struct`\<\{ `goal`: `NullOr`\<`Struct`\<\{ `revision`: `String`; `objective`: `String`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`\]\>; `startedAt`: `Int`; `pauseCause`: `NullOr`\<`Struct`\<\{ `kind`: `Literals`\<...\>; `detail`: `NullOr`\<...\>; \}\>\>; \}\>\>; `ended`: `$Array`\<`Struct`\<\{ `sequence`: `Int`; `objective`: `String`; `outcome`: `Literals`\<readonly \[`"achieved"`, `"cleared"`\]\>; `reason`: `NullOr`\<`String`\>; `endedAt`: `Int`; `afterSequence`: `Int`; \}\>\>; `omitted`: `Int`; \}\> | `GoalProjection` | Decoder for the goal projection. |
|
|
@@ -20,49 +20,6 @@ One Session's loop.
|
|
|
20
20
|
|
|
21
21
|
## Variables
|
|
22
22
|
|
|
23
|
-
### LoopCron
|
|
24
|
-
|
|
25
|
-
```ts
|
|
26
|
-
const LoopCron: Struct<{
|
|
27
|
-
expression: String;
|
|
28
|
-
timeZone: String;
|
|
29
|
-
}>;
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
A named cron cadence evaluated in one IANA time zone.
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
### Loop
|
|
37
|
-
|
|
38
|
-
```ts
|
|
39
|
-
const Loop: Struct<{
|
|
40
|
-
loopId: String;
|
|
41
|
-
origin: Literals<readonly ["human", "model"]>;
|
|
42
|
-
expiresAt: NullOr<Int>;
|
|
43
|
-
prompt: String;
|
|
44
|
-
mode: Literals<readonly ["self_paced", "fixed_interval"]>;
|
|
45
|
-
cron: NullOr<
|
|
46
|
-
Struct<{
|
|
47
|
-
expression: String;
|
|
48
|
-
timeZone: String;
|
|
49
|
-
}>
|
|
50
|
-
>;
|
|
51
|
-
state: Literals<
|
|
52
|
-
readonly ["active", "paused", "finished", "failed", "cancelled"]
|
|
53
|
-
>;
|
|
54
|
-
commandId: String;
|
|
55
|
-
reason: NullOr<String>;
|
|
56
|
-
nextDueAt: NullOr<Int>;
|
|
57
|
-
lastError: NullOr<String>;
|
|
58
|
-
consecutiveFailures: Int;
|
|
59
|
-
}>;
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
One Session's loop as every client sees it.
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
23
|
### LoopCommandInput
|
|
67
24
|
|
|
68
25
|
```ts
|
|
@@ -128,37 +85,96 @@ Loop's contract: Session-scope controls and one projection slot.
|
|
|
128
85
|
const loopContract: object;
|
|
129
86
|
```
|
|
130
87
|
|
|
131
|
-
Session-owned
|
|
88
|
+
Session-owned current-Loop controls and Agent-scoped identified-Loop controls.
|
|
132
89
|
|
|
133
90
|
#### Type Declaration
|
|
134
91
|
|
|
135
|
-
| Name | Type | Default value | Description
|
|
136
|
-
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
137
|
-
| <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity.
|
|
138
|
-
| <a id="property-commands"></a> `commands` | `object` | - | Loop operations admitted by
|
|
139
|
-
| `commands.
|
|
140
|
-
| `commands.
|
|
141
|
-
| `commands.
|
|
142
|
-
| `commands.
|
|
143
|
-
| `commands.
|
|
144
|
-
| `commands.
|
|
145
|
-
| `commands.
|
|
146
|
-
| `commands.
|
|
147
|
-
| `commands.
|
|
148
|
-
| `commands.
|
|
149
|
-
| `commands.
|
|
150
|
-
| `commands.
|
|
151
|
-
| `commands.
|
|
152
|
-
| `commands.
|
|
153
|
-
| `commands.
|
|
154
|
-
| `commands.
|
|
155
|
-
| `commands.
|
|
156
|
-
| `commands.
|
|
157
|
-
| `commands.
|
|
158
|
-
| `commands.
|
|
159
|
-
| `commands.
|
|
160
|
-
| `commands.
|
|
161
|
-
| `commands.
|
|
162
|
-
| `commands.
|
|
163
|
-
|
|
|
164
|
-
| `
|
|
92
|
+
| Name | Type | Default value | Description |
|
|
93
|
+
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------ |
|
|
94
|
+
| <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity. |
|
|
95
|
+
| <a id="property-commands"></a> `commands` | `object` | - | Loop operations admitted by their Agent or Session owner. |
|
|
96
|
+
| `commands.list` | `object` | - | Read an Agent's bounded Loop page, including each destination Session. |
|
|
97
|
+
| `commands.list.scope` | `"agent"` | `"agent"` | The Agent owns the collection of its Sessions' Loops. |
|
|
98
|
+
| `commands.list.input` | `Struct`\<\{ `after`: `optionalKey`\<`String`\>; `limit`: `optionalKey`\<`Int`\>; \}\> | `LoopListInput` | Page strictly after a Session identity, in identity order. |
|
|
99
|
+
| `commands.list.output` | `$Array`\<`Struct`\<\{ `sessionId`: `String`; `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`; \}\>\> | - | Public Loop values with Session targets, never private scheduling state. |
|
|
100
|
+
| `commands.pauseLoop` | `object` | - | Pause an identified Loop; refuse a stale target after replacement. |
|
|
101
|
+
| `commands.pauseLoop.scope` | `"agent"` | `"agent"` | The Agent owns the identified Loop and its Session. |
|
|
102
|
+
| `commands.pauseLoop.input` | `Struct`\<\{ `sessionId`: `String`; `loopId`: `String`; \}\> | `LoopTarget` | The listed Session and Loop identities must both still match. |
|
|
103
|
+
| `commands.pauseLoop.output` | `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`; \}\> | `Loop` | Return the paused Loop without cancelling accepted work. |
|
|
104
|
+
| `commands.resumeLoop` | `object` | - | Resume an identified Loop; refuse a stale target after replacement. |
|
|
105
|
+
| `commands.resumeLoop.scope` | `"agent"` | `"agent"` | The Agent owns the identified Loop and its Session. |
|
|
106
|
+
| `commands.resumeLoop.input` | `Struct`\<\{ `sessionId`: `String`; `loopId`: `String`; \}\> | `LoopTarget` | The listed Session and Loop identities must both still match. |
|
|
107
|
+
| `commands.resumeLoop.output` | `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`; \}\> | `Loop` | Return the resumed Loop without changing accepted work. |
|
|
108
|
+
| `commands.stopLoop` | `object` | - | Cancel an identified Loop's future occurrences, retaining accepted work. |
|
|
109
|
+
| `commands.stopLoop.scope` | `"agent"` | `"agent"` | The Agent owns the identified Loop and its Session. |
|
|
110
|
+
| `commands.stopLoop.input` | `Struct`\<\{ `sessionId`: `String`; `loopId`: `String`; \}\> | `LoopTarget` | The listed Session and Loop identities must both still match. |
|
|
111
|
+
| `commands.stopLoop.output` | `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`; \}\> | `Loop` | Return the cancelled Loop; its Session and history remain. |
|
|
112
|
+
| `commands.loop` | `object` | - | Open or answer the human loop controls. |
|
|
113
|
+
| `commands.loop.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
114
|
+
| `commands.loop.input` | `Union`\<readonly \[`Struct`\<\{ `action`: `Literal`\<`"start"`\>; `text`: `String`; `requestId`: `String`; \}\>, `Struct`\<\{ `action`: `Literals`\<readonly \[`"status"`, `"pause"`, `"resume"`, `"stop"`, `"stop-ask"`, `"new"`\]\>; `confirmed`: `optional`\<`Boolean`\>; \}\>, `Struct`\<\{ \}\>\]\> | `LoopCommandInput` | Decode the selected human action. |
|
|
115
|
+
| `commands.loop.output` | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\> | `CatalogStep` | Return the server-owned conversation step. |
|
|
116
|
+
| `commands.startSelfPaced` | `object` | - | Start a loop whose next occurrence is chosen by the model. |
|
|
117
|
+
| `commands.startSelfPaced.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
118
|
+
| `commands.startSelfPaced.input` | `Struct`\<\{ `prompt`: `String`; `requestId`: `String`; \}\> | - | Decode the repeated prompt and command identity. |
|
|
119
|
+
| `commands.startSelfPaced.output` | `Struct`\<\{ `loop`: `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`; \}\>; `accepted`: `Struct`\<\{ `status`: `Literal`\<`"accepted"`\>; `commandId`: `String`; \}\>; \}\> | `StartResult` | Return the loop and admission receipt. |
|
|
120
|
+
| `commands.startFixedInterval` | `object` | - | Start a loop with a fixed cron cadence. |
|
|
121
|
+
| `commands.startFixedInterval.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
122
|
+
| `commands.startFixedInterval.input` | `Struct`\<\{ `prompt`: `String`; `requestId`: `String`; `expression`: `String`; `timeZone`: `String`; \}\> | - | Decode the prompt, cadence and command identity. |
|
|
123
|
+
| `commands.startFixedInterval.output` | `Struct`\<\{ `loop`: `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`; \}\>; `accepted`: `Struct`\<\{ `status`: `Literal`\<`"accepted"`\>; `commandId`: `String`; \}\>; \}\> | `StartResult` | Return the loop and admission receipt. |
|
|
124
|
+
| `commands.pause` | `object` | - | Suspend the current loop. |
|
|
125
|
+
| `commands.pause.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
126
|
+
| `commands.pause.input` | `Struct`\<\{ \}\> | - | No additional arguments are required. |
|
|
127
|
+
| `commands.pause.output` | `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`; \}\> | `Loop` | Return the paused loop. |
|
|
128
|
+
| `commands.resume` | `object` | - | Resume the current paused loop. |
|
|
129
|
+
| `commands.resume.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
130
|
+
| `commands.resume.input` | `Struct`\<\{ \}\> | - | No additional arguments are required. |
|
|
131
|
+
| `commands.resume.output` | `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`; \}\> | `Loop` | Return the resumed loop. |
|
|
132
|
+
| `commands.stop` | `object` | - | Stop future occurrences of the current loop. |
|
|
133
|
+
| `commands.stop.scope` | `"session"` | `"session"` | The Session owns this loop. |
|
|
134
|
+
| `commands.stop.input` | `Struct`\<\{ \}\> | - | No additional arguments are required. |
|
|
135
|
+
| `commands.stop.output` | `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`; \}\> | `Loop` | Return the stopped loop. |
|
|
136
|
+
| <a id="property-projection"></a> `projection` | `object` | - | Current loop visible to Session clients. |
|
|
137
|
+
| `projection.schema` | `Struct`\<\{ `loop`: `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`; \}\>; \}\> | `LoopProjection` | Decoder for projected loop state. |
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
### LoopCron
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
const LoopCron: Struct<{
|
|
145
|
+
expression: String;
|
|
146
|
+
timeZone: String;
|
|
147
|
+
}>;
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
A named cron cadence evaluated in one IANA time zone.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
### Loop
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
const Loop: Struct<{
|
|
158
|
+
loopId: String;
|
|
159
|
+
origin: Literals<readonly ["human", "model"]>;
|
|
160
|
+
expiresAt: NullOr<Int>;
|
|
161
|
+
prompt: String;
|
|
162
|
+
mode: Literals<readonly ["self_paced", "fixed_interval"]>;
|
|
163
|
+
cron: NullOr<
|
|
164
|
+
Struct<{
|
|
165
|
+
expression: String;
|
|
166
|
+
timeZone: String;
|
|
167
|
+
}>
|
|
168
|
+
>;
|
|
169
|
+
state: Literals<
|
|
170
|
+
readonly ["active", "paused", "finished", "failed", "cancelled"]
|
|
171
|
+
>;
|
|
172
|
+
commandId: String;
|
|
173
|
+
reason: NullOr<String>;
|
|
174
|
+
nextDueAt: NullOr<Int>;
|
|
175
|
+
lastError: NullOr<String>;
|
|
176
|
+
consecutiveFailures: Int;
|
|
177
|
+
}>;
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
One Session's loop as every client sees it.
|
|
@@ -8,6 +8,24 @@
|
|
|
8
8
|
|
|
9
9
|
# roster/conversation-agents
|
|
10
10
|
|
|
11
|
+
## Type Aliases
|
|
12
|
+
|
|
13
|
+
### SendingDirectory
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
type SendingDirectory = Omit<AgentControlDirectory, "open"> & Readonly<{
|
|
17
|
+
open: (agentId, signal) => Promise<Readonly<{
|
|
18
|
+
agent: Readonly<{
|
|
19
|
+
session: (sessionId) => Pick<..., ...>;
|
|
20
|
+
}>;
|
|
21
|
+
release: () => Promise<void>;
|
|
22
|
+
}>>;
|
|
23
|
+
}>;
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The directory a conversation sends through; opening a recipient only needs its
|
|
27
|
+
Sessions' extension doors.
|
|
28
|
+
|
|
11
29
|
## Functions
|
|
12
30
|
|
|
13
31
|
### assertOrdinaryAgentCreation()
|
|
@@ -31,6 +49,28 @@ owners.
|
|
|
31
49
|
|
|
32
50
|
---
|
|
33
51
|
|
|
52
|
+
### adoptDelegatedGoal()
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
function adoptDelegatedGoal(session, input): Promise<void>;
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Adopt the first accepted turn once, even when the sender was offline at
|
|
59
|
+
delivery.
|
|
60
|
+
|
|
61
|
+
#### Parameters
|
|
62
|
+
|
|
63
|
+
| Parameter | Type |
|
|
64
|
+
| --------- | -------------------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `session` | `Pick`\<`ShiitakeSession`, `"extension"`\> |
|
|
66
|
+
| `input` | `Readonly`\<\{ `text`: `string`; `goal`: `string` \| `false` \| `undefined`; `commandId`: `string`; \}\> |
|
|
67
|
+
|
|
68
|
+
#### Returns
|
|
69
|
+
|
|
70
|
+
`Promise`\<`void`\>
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
34
74
|
### createConversationAgents()
|
|
35
75
|
|
|
36
76
|
```ts
|
|
@@ -54,7 +94,7 @@ child.
|
|
|
54
94
|
|
|
55
95
|
| Name | Type | Description |
|
|
56
96
|
| ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
57
|
-
| `recording()` | (`parentSessionId`, `directory`) => `
|
|
97
|
+
| `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. |
|
|
58
98
|
| `control()` | (`directoryFor`) => `CapabilitySource` | Agent-control tools bound to the conversation that acquires them. |
|
|
59
99
|
| `source()` | (`directory`) => [`SubagentSource`](../subagents/host.md#subagentsource) | The footer rows for one conversation; archived and unknown Agents leave it. |
|
|
60
100
|
|