@fungi.computer/shiitake-extensions 0.3.0 → 0.5.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 (39) hide show
  1. package/README.md +20 -16
  2. package/dist/goal/contract.d.ts +6 -0
  3. package/dist/goal/contract.js +6 -0
  4. package/dist/goal/host.js +183 -31
  5. package/dist/loop/contract.d.ts +136 -2
  6. package/dist/loop/contract.js +45 -2
  7. package/dist/loop/host.js +23 -0
  8. package/dist/question/answer-flow.d.ts +27 -0
  9. package/dist/question/answer-flow.js +115 -0
  10. package/dist/question/client.d.ts +1 -1
  11. package/dist/question/client.js +22 -3
  12. package/dist/question/contract.d.ts +202 -60
  13. package/dist/question/contract.js +78 -22
  14. package/dist/question/host.d.ts +4 -0
  15. package/dist/question/host.js +348 -339
  16. package/dist/roster/conversation-agents.d.ts +21 -1
  17. package/dist/roster/conversation-agents.js +47 -2
  18. package/dist/roster.d.ts +5 -2
  19. package/dist/roster.js +16 -5
  20. package/dist/schedules.d.ts +178 -0
  21. package/dist/schedules.js +182 -0
  22. package/dist/subagents/client.js +64 -20
  23. package/dist/subagents/contract.d.ts +123 -10
  24. package/dist/subagents/contract.js +38 -5
  25. package/dist/subagents/host.d.ts +2 -4
  26. package/dist/subagents/host.js +152 -22
  27. package/docs/api/README.md +1 -0
  28. package/docs/api/goal/contract.md +1 -1
  29. package/docs/api/goal/host.md +22 -1
  30. package/docs/api/loop/contract.md +43 -31
  31. package/docs/api/question/client.md +2 -1
  32. package/docs/api/question/contract.md +183 -51
  33. package/docs/api/question/host.md +30 -0
  34. package/docs/api/roster/conversation-agents.md +34 -8
  35. package/docs/api/roster.md +39 -2
  36. package/docs/api/schedules.md +481 -0
  37. package/docs/api/subagents/contract.md +101 -28
  38. package/docs/api/subagents/host.md +5 -3
  39. package/package.json +9 -6
package/docs/api/subagents/contract.md CHANGED
@@ -54,13 +54,21 @@ The most Agents one conversation's footer lists; the rest are counted.
54
54
 
55
55
  ```ts
56
56
  const SubagentState: Literals<
57
- readonly ["working", "waiting", "idle", "failed", "unavailable"]
57
+ readonly [
58
+ "working",
59
+ "waiting_on_agent",
60
+ "needs_you",
61
+ "idle",
62
+ "failed",
63
+ "unavailable",
64
+ ]
58
65
  >;
59
66
  ```
60
67
 
61
- What the human sees for one ordinary created Agent. `waiting` is any open
62
- attention on its conversation (a question or a tool approval); `unavailable`
63
- means its status could not be read, and is never shown as idle.
68
+ What the human sees for one ordinary created Agent. `waiting_on_agent` is an
69
+ open question that waits on the Agent that sent the work, calm until it is
70
+ escalated; `needs_you` is attention that waits on a person; `unavailable` means
71
+ its status could not be read, and is never shown as idle.
64
72
 
65
73
  ---
66
74
 
@@ -71,10 +79,22 @@ const Subagent: Struct<{
71
79
  agentId: String;
72
80
  name: String;
73
81
  sessionId: NullOr<String>;
74
- state: Literals<
75
- readonly ["working", "waiting", "idle", "failed", "unavailable"]
76
- >;
82
+ state: Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
77
83
  attention: optionalKey<String>;
84
+ waitingOn: optionalKey<String>;
85
+ ask: optionalKey<Struct<{
86
+ askId: String;
87
+ questions: $Array<Struct<{
88
+ id: String;
89
+ header: String;
90
+ question: String;
91
+ options: $Array<Struct<{
92
+ label: ...;
93
+ description: ...;
94
+ }>>;
95
+ multiple: optionalKey<Boolean>;
96
+ }>>;
97
+ }>>;
78
98
  }>;
79
99
  ```
80
100
 
@@ -87,17 +107,24 @@ work.
87
107
 
88
108
  ```ts
89
109
  const SubagentsProjection: Struct<{
90
- agents: $Array<
91
- Struct<{
92
- agentId: String;
93
- name: String;
94
- sessionId: NullOr<String>;
95
- state: Literals<
96
- readonly ["working", "waiting", "idle", "failed", "unavailable"]
97
- >;
98
- attention: optionalKey<String>;
99
- }>
100
- >;
110
+ agents: $Array<Struct<{
111
+ agentId: String;
112
+ name: String;
113
+ sessionId: NullOr<String>;
114
+ state: Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
115
+ attention: optionalKey<String>;
116
+ waitingOn: optionalKey<String>;
117
+ ask: optionalKey<Struct<{
118
+ askId: String;
119
+ questions: $Array<Struct<{
120
+ id: ...;
121
+ header: ...;
122
+ question: ...;
123
+ options: ...;
124
+ multiple: ...;
125
+ }>>;
126
+ }>>;
127
+ }>>;
101
128
  more: Int;
102
129
  expanded: Boolean;
103
130
  }>;
@@ -109,6 +136,48 @@ footer keeps one summary row.
109
136
 
110
137
  ---
111
138
 
139
+ ### AnswerChildInput
140
+
141
+ ```ts
142
+ const AnswerChildInput: Union<
143
+ Struct<
144
+ | {
145
+ askId: String;
146
+ requestId: String;
147
+ index: Number;
148
+ answers: $Record<
149
+ String,
150
+ Struct<{
151
+ selected: $Array<String>;
152
+ text: optionalKey<String>;
153
+ }>
154
+ >;
155
+ stage: Literal<"decision">;
156
+ answer: Struct<{
157
+ selected: $Array<String>;
158
+ text: optionalKey<String>;
159
+ }>;
160
+ agentId: String;
161
+ sessionId: String;
162
+ }
163
+ | {
164
+ askId: String;
165
+ agentId: String;
166
+ sessionId: String;
167
+ }
168
+ | {
169
+ agentId: String;
170
+ sessionId: String;
171
+ }
172
+ >[]
173
+ >;
174
+ ```
175
+
176
+ The question flow's own steps, each naming the child whose Ask they answer. The
177
+ footer owns the conversation; the child's question owner commits it.
178
+
179
+ ---
180
+
112
181
  ### subagentsContract
113
182
 
114
183
  ```ts
@@ -119,13 +188,17 @@ Created-Agent footer control and its visible projection.
119
188
 
120
189
  #### Type Declaration
121
190
 
122
- | Name | Type | Default value | Description |
123
- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------- |
124
- | <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity. |
125
- | <a id="property-commands"></a> `commands` | `object` | - | Human footer controls. |
126
- | `commands.agents` | `object` | - | Toggle the created-Agent footer between expanded and summarized views. |
127
- | `commands.agents.scope` | `"session"` | `"session"` | The Session owns its footer view. |
128
- | `commands.agents.input` | `Struct`\<\{ \}\> | - | No additional arguments are required. |
129
- | `commands.agents.output` | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\> | `CatalogStep` | Return the server-owned human control step. |
130
- | <a id="property-projection"></a> `projection` | `object` | - | Footer rows and expansion state. |
131
- | `projection.schema` | `Struct`\<\{ `agents`: `$Array`\<`Struct`\<\{ `agentId`: `String`; `name`: `String`; `sessionId`: `NullOr`\<`String`\>; `state`: `Literals`\<readonly \[`"working"`, `"waiting"`, `"idle"`, `"failed"`, `"unavailable"`\]\>; `attention`: `optionalKey`\<`String`\>; \}\>\>; `more`: `Int`; `expanded`: `Boolean`; \}\> | `SubagentsProjection` | Decoder for the projected footer. |
191
+ | Name | Type | Default value | Description |
192
+ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------- |
193
+ | <a id="property-id"></a> `id` | `string` & `Brand`\<`"ExtensionId"`\> | - | Stable extension identity. |
194
+ | <a id="property-commands"></a> `commands` | `object` | - | Human footer controls. |
195
+ | `commands.agents` | `object` | - | Toggle the created-Agent footer between expanded and summarized views. |
196
+ | `commands.agents.scope` | `"session"` | `"session"` | The Session owns its footer view. |
197
+ | `commands.agents.input` | `Struct`\<\{ \}\> | - | No additional arguments are required. |
198
+ | `commands.agents.output` | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\> | `CatalogStep` | Return the server-owned human control step. |
199
+ | `commands.answerChild` | `object` | - | Answer a question an escalated sub-agent asks, from this conversation. |
200
+ | `commands.answerChild.scope` | `"session"` | `"session"` | The Session owns its footer. |
201
+ | `commands.answerChild.input` | `Union`\<`Struct`\< \| \{ `askId`: `String`; `requestId`: `String`; `index`: `Number`; `answers`: `$Record`\<`String`, `Struct`\<\{ `selected`: ...; `text`: ...; \}\>\>; `stage`: `Literal`\<`"decision"`\>; `answer`: `Struct`\<\{ `selected`: `$Array`\<...\>; `text`: `optionalKey`\<...\>; \}\>; `agentId`: `String`; `sessionId`: `String`; \} \| \{ `askId`: `String`; `agentId`: `String`; `sessionId`: `String`; \} \| \{ `agentId`: `String`; `sessionId`: `String`; \}\>[]\> | `AnswerChildInput` | The next step of the child's answer conversation. |
202
+ | `commands.answerChild.output` | `declare`\<`WhistleCatalogStepV1`, `WhistleCatalogStepV1`\> | `CatalogStep` | Return the next human conversation step. |
203
+ | <a id="property-projection"></a> `projection` | `object` | - | Footer rows and expansion state. |
204
+ | `projection.schema` | `Struct`\<\{ `agents`: `$Array`\<`Struct`\<\{ `agentId`: `String`; `name`: `String`; `sessionId`: `NullOr`\<`String`\>; `state`: `Literals`\<readonly \[`"working"`, `"waiting_on_agent"`, `"needs_you"`, `"idle"`, `"failed"`, `"unavailable"`\]\>; `attention`: `optionalKey`\<`String`\>; `waitingOn`: `optionalKey`\<`String`\>; `ask`: `optionalKey`\<`Struct`\<\{ `askId`: `String`; `questions`: `$Array`\<...\>; \}\>\>; \}\>\>; `more`: `Int`; `expanded`: `Boolean`; \}\> | `SubagentsProjection` | Decoder for the projected footer. |
package/docs/api/subagents/host.md CHANGED
@@ -29,11 +29,13 @@ A footer row for an ordinary Agent created by the current Agent.
29
29
  ```ts
30
30
  type SubagentAgent = Readonly<{
31
31
  listSessions: ShiitakeAgent["listSessions"];
32
- session: (sessionId) => Pick<ShiitakeSession, "read">;
32
+ session: (
33
+ sessionId,
34
+ ) => Pick<ShiitakeSession, "read" | "readSettlement" | "extension">;
33
35
  }>;
34
36
  ```
35
37
 
36
- The two owner reads a status needs from one child Agent.
38
+ Owner reads used for status and exact delegated command settlement.
37
39
 
38
40
  ---
39
41
 
@@ -41,6 +43,7 @@ The two owner reads a status needs from one child Agent.
41
43
 
42
44
  ```ts
43
45
  type SubagentSource = Readonly<{
46
+ hasLiveChildCommand: (sessionId) => boolean;
44
47
  read: (
45
48
  sessionId,
46
49
  limit,
@@ -75,7 +78,6 @@ stops the Agent's work.
75
78
  type SubagentTiming = Readonly<{
76
79
  refreshMs: number;
77
80
  pollMs: number;
78
- interestMs: number;
79
81
  }>;
80
82
  ```
81
83
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fungi.computer/shiitake-extensions",
3
- "version": "0.3.0",
3
+ "version": "0.5.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",
@@ -46,6 +46,10 @@
46
46
  "types": "./dist/roster.d.ts",
47
47
  "import": "./dist/roster.js"
48
48
  },
49
+ "./schedules": {
50
+ "types": "./dist/schedules.d.ts",
51
+ "import": "./dist/schedules.js"
52
+ },
49
53
  "./roster/conversation-agents": {
50
54
  "types": "./dist/roster/conversation-agents.d.ts",
51
55
  "import": "./dist/roster/conversation-agents.js"
@@ -108,13 +112,12 @@
108
112
  "dependencies": {
109
113
  "@fungi.computer/almanac": "0.2.0",
110
114
  "@fungi.computer/cairn": "0.1.0",
111
- "@fungi.computer/knapsack": "0.3.1",
112
- "@fungi.computer/mycelium": "0.2.2",
113
- "@fungi.computer/shiitake": "0.5.0",
115
+ "@fungi.computer/knapsack": "0.4.1",
116
+ "@fungi.computer/mycelium": "0.3.0",
117
+ "@fungi.computer/shiitake": "0.7.0",
114
118
  "@fungi.computer/watchdog": "0.1.0",
115
- "@fungi.computer/whistle": "0.2.0",
119
+ "@fungi.computer/whistle": "0.3.0",
116
120
  "effect": "4.0.2",
117
- "papaparse": "5.7.0",
118
121
  "zod": "4.4.3",
119
122
  "@fungi.computer/gills": "0.2.0"
120
123
  },