@introspection-ai/recipes 0.13.0 → 0.14.1

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 (222) hide show
  1. package/README.md +46 -57
  2. package/dist/{agent-tool.d.ts → agents.d.ts} +4 -1
  3. package/dist/agents.d.ts.map +1 -0
  4. package/dist/{agent-tool.js → agents.js} +1 -1
  5. package/dist/agents.js.map +1 -0
  6. package/dist/api/extensions.d.ts +3 -0
  7. package/dist/api/extensions.d.ts.map +1 -0
  8. package/dist/api/extensions.js +2 -0
  9. package/dist/api/extensions.js.map +1 -0
  10. package/dist/api/mcp.d.ts +4 -0
  11. package/dist/api/mcp.d.ts.map +1 -0
  12. package/dist/api/mcp.js +2 -0
  13. package/dist/api/mcp.js.map +1 -0
  14. package/dist/api/session.d.ts +3 -0
  15. package/dist/api/session.d.ts.map +1 -0
  16. package/dist/api/session.js +2 -0
  17. package/dist/api/session.js.map +1 -0
  18. package/dist/child-agent.d.ts +5 -4
  19. package/dist/child-agent.d.ts.map +1 -1
  20. package/dist/child-agent.js +26 -117
  21. package/dist/child-agent.js.map +1 -1
  22. package/dist/child-session.d.ts +23 -0
  23. package/dist/child-session.d.ts.map +1 -0
  24. package/dist/child-session.js +48 -0
  25. package/dist/child-session.js.map +1 -0
  26. package/dist/extensions.d.ts +29 -0
  27. package/dist/extensions.d.ts.map +1 -0
  28. package/dist/extensions.js +119 -0
  29. package/dist/extensions.js.map +1 -0
  30. package/dist/index.d.ts +4 -13
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +2 -13
  33. package/dist/index.js.map +1 -1
  34. package/dist/inspect.d.ts +38 -5
  35. package/dist/inspect.d.ts.map +1 -1
  36. package/dist/inspect.js +92 -41
  37. package/dist/inspect.js.map +1 -1
  38. package/dist/interactions.d.ts +18 -2
  39. package/dist/interactions.d.ts.map +1 -1
  40. package/dist/interactions.js +41 -10
  41. package/dist/interactions.js.map +1 -1
  42. package/dist/mcp-catalog.d.ts +1 -0
  43. package/dist/mcp-catalog.d.ts.map +1 -1
  44. package/dist/mcp-catalog.js +14 -6
  45. package/dist/mcp-catalog.js.map +1 -1
  46. package/dist/mcp-chunks/auth-command-ZLGYIEUY.js +273 -0
  47. package/dist/mcp-chunks/call-arguments-LU3W6D3K.js +13 -0
  48. package/dist/mcp-chunks/call-command-LKTKSYTH.js +612 -0
  49. package/dist/mcp-chunks/chunk-2U4BSDC4.js +3951 -0
  50. package/dist/mcp-chunks/chunk-2XL7MG7R.js +272 -0
  51. package/dist/mcp-chunks/chunk-3BJA27PY.js +2321 -0
  52. package/dist/mcp-chunks/chunk-4SQKWYFF.js +15 -0
  53. package/dist/mcp-chunks/chunk-5QOSCSQB.js +290 -0
  54. package/dist/mcp-chunks/chunk-6W5QFASN.js +77 -0
  55. package/dist/mcp-chunks/chunk-6XCZGU3G.js +1004 -0
  56. package/dist/mcp-chunks/chunk-7FHEBT5G.js +149 -0
  57. package/dist/mcp-chunks/chunk-7KA2VJVZ.js +114 -0
  58. package/dist/mcp-chunks/chunk-7UDVSOOF.js +138 -0
  59. package/dist/mcp-chunks/chunk-BNV3TPE4.js +66 -0
  60. package/dist/mcp-chunks/chunk-BTLAWHTA.js +129 -0
  61. package/dist/mcp-chunks/chunk-BV56DXPW.js +13 -0
  62. package/dist/mcp-chunks/chunk-BWHIA4PC.js +90 -0
  63. package/dist/mcp-chunks/chunk-BZIQOWE6.js +267 -0
  64. package/dist/mcp-chunks/chunk-D3MRAZ6H.js +16140 -0
  65. package/dist/mcp-chunks/chunk-DHBE7UBH.js +750 -0
  66. package/dist/mcp-chunks/chunk-E22DYOW5.js +251 -0
  67. package/dist/mcp-chunks/chunk-ECIVB7P4.js +139 -0
  68. package/dist/mcp-chunks/chunk-HKRJ6O36.js +1076 -0
  69. package/dist/mcp-chunks/chunk-IABRYROW.js +44 -0
  70. package/dist/mcp-chunks/chunk-J6LYIZXN.js +45 -0
  71. package/dist/mcp-chunks/chunk-L7NTQVYN.js +161 -0
  72. package/dist/mcp-chunks/chunk-LEZSACDE.js +141 -0
  73. package/dist/mcp-chunks/chunk-LKIBAYKU.js +208 -0
  74. package/dist/mcp-chunks/chunk-LNH5LAJD.js +152 -0
  75. package/dist/mcp-chunks/chunk-LQQEYD76.js +124 -0
  76. package/dist/mcp-chunks/chunk-LRKZP7DJ.js +47 -0
  77. package/dist/mcp-chunks/chunk-LS7PMWSR.js +109 -0
  78. package/dist/mcp-chunks/chunk-M3TPODXI.js +95 -0
  79. package/dist/mcp-chunks/chunk-MZ2NARG7.js +400 -0
  80. package/dist/mcp-chunks/chunk-N46NEFAF.js +45 -0
  81. package/dist/mcp-chunks/chunk-NNOEGEUZ.js +17273 -0
  82. package/dist/mcp-chunks/chunk-NRAJX5E4.js +69 -0
  83. package/dist/mcp-chunks/chunk-P3PSC54P.js +869 -0
  84. package/dist/mcp-chunks/chunk-PIIYJR44.js +6341 -0
  85. package/dist/mcp-chunks/chunk-PWYFKGKG.js +385 -0
  86. package/dist/mcp-chunks/chunk-SJCCBNZ4.js +45 -0
  87. package/dist/mcp-chunks/chunk-TATVT5IT.js +194 -0
  88. package/dist/mcp-chunks/chunk-TEUKFFQL.js +29 -0
  89. package/dist/mcp-chunks/chunk-UKYNQGNE.js +150 -0
  90. package/dist/mcp-chunks/chunk-UNKB4SBV.js +37 -0
  91. package/dist/mcp-chunks/chunk-WD6BOD24.js +138 -0
  92. package/dist/mcp-chunks/chunk-WQJZMCJN.js +73 -0
  93. package/dist/mcp-chunks/chunk-XANPGTLI.js +364 -0
  94. package/dist/mcp-chunks/chunk-XQK2JSW4.js +35 -0
  95. package/dist/mcp-chunks/chunk-YHQUTU6L.js +571 -0
  96. package/dist/mcp-chunks/chunk-YVZKMV5H.js +57 -0
  97. package/dist/mcp-chunks/cli-UV4QJZZM.js +929 -0
  98. package/dist/mcp-chunks/client-S7RQUG5U.js +13 -0
  99. package/dist/mcp-chunks/config-command-NLAGKID5.js +1101 -0
  100. package/dist/mcp-chunks/daemon-command-U242Z6VY.js +26 -0
  101. package/dist/mcp-chunks/dist-LK3SHAMX.js +6478 -0
  102. package/dist/mcp-chunks/emit-ts-command-VBXVXO6V.js +386 -0
  103. package/dist/mcp-chunks/generate-cli-runner-6CAZZA3P.js +1426 -0
  104. package/dist/mcp-chunks/inspect-cli-command-3ZORTOR7.js +111 -0
  105. package/dist/mcp-chunks/launch-YKRXHXJI.js +10 -0
  106. package/dist/mcp-chunks/lifecycle-XVKRHPH3.js +16 -0
  107. package/dist/mcp-chunks/list-command-2MEGGNFQ.js +4190 -0
  108. package/dist/mcp-chunks/output-utils-NKESLAJ6.js +12 -0
  109. package/dist/mcp-chunks/prompt-B1Yc1NPt-VGOTWJMN.js +918 -0
  110. package/dist/mcp-chunks/record-command-YXHTTTT5.js +17 -0
  111. package/dist/mcp-chunks/replay-command-25HJ6AQU.js +85 -0
  112. package/dist/mcp-chunks/resource-command-OO4NYF5C.js +97 -0
  113. package/dist/mcp-chunks/result-utils-MOHHLNM7.js +15 -0
  114. package/dist/mcp-chunks/runtime-5WJ3G25Y.js +33 -0
  115. package/dist/mcp-chunks/runtime-wrapper-RPWDIDBF.js +10 -0
  116. package/dist/mcp-chunks/serve-command-DHXJZMMN.js +3302 -0
  117. package/dist/mcp-chunks/timeouts-W2XWCCXR.js +18 -0
  118. package/dist/mcp-chunks/vault-command-PIYIUEZL.js +154 -0
  119. package/dist/mcp-daemon-client.d.ts +6 -1
  120. package/dist/mcp-daemon-client.d.ts.map +1 -1
  121. package/dist/mcp-daemon-client.js +119 -2
  122. package/dist/mcp-daemon-client.js.map +1 -1
  123. package/dist/mcp-daemon-protocol.d.ts +18 -1
  124. package/dist/mcp-daemon-protocol.d.ts.map +1 -1
  125. package/dist/mcp-daemon-protocol.js +31 -0
  126. package/dist/mcp-daemon-protocol.js.map +1 -1
  127. package/dist/mcp-daemon.js +169 -76602
  128. package/dist/mcp-daemon.js.map +1 -1
  129. package/dist/mcp-policy.d.ts +11 -0
  130. package/dist/mcp-policy.d.ts.map +1 -0
  131. package/dist/mcp-policy.js +27 -0
  132. package/dist/mcp-policy.js.map +1 -0
  133. package/dist/mcp-run-worker.js +38 -76540
  134. package/dist/mcp-tools.d.ts +39 -0
  135. package/dist/mcp-tools.d.ts.map +1 -0
  136. package/dist/mcp-tools.js +493 -0
  137. package/dist/mcp-tools.js.map +1 -0
  138. package/dist/mcp.d.ts +21 -9
  139. package/dist/mcp.d.ts.map +1 -1
  140. package/dist/mcp.js +101 -31
  141. package/dist/mcp.js.map +1 -1
  142. package/dist/model-binding.d.ts +39 -0
  143. package/dist/model-binding.d.ts.map +1 -0
  144. package/dist/model-binding.js +103 -0
  145. package/dist/model-binding.js.map +1 -0
  146. package/dist/pi-extension.d.ts +2 -22
  147. package/dist/pi-extension.d.ts.map +1 -1
  148. package/dist/pi-extension.js +296 -71
  149. package/dist/pi-extension.js.map +1 -1
  150. package/dist/recipe/resolve.d.ts +43 -20
  151. package/dist/recipe/resolve.d.ts.map +1 -1
  152. package/dist/recipe/resolve.js +215 -70
  153. package/dist/recipe/resolve.js.map +1 -1
  154. package/dist/recipe-agent.d.ts +24 -27
  155. package/dist/recipe-agent.d.ts.map +1 -1
  156. package/dist/recipe-agent.js +278 -230
  157. package/dist/recipe-agent.js.map +1 -1
  158. package/dist/recipe-check.d.ts +18 -0
  159. package/dist/recipe-check.d.ts.map +1 -0
  160. package/dist/recipe-check.js +261 -0
  161. package/dist/recipe-check.js.map +1 -0
  162. package/dist/recipe-extensions.d.ts.map +1 -1
  163. package/dist/recipe-extensions.js +0 -3
  164. package/dist/recipe-extensions.js.map +1 -1
  165. package/dist/recipe-model.d.ts +3 -1
  166. package/dist/recipe-model.d.ts.map +1 -1
  167. package/dist/recipe-model.js +15 -12
  168. package/dist/recipe-model.js.map +1 -1
  169. package/dist/recipe-package.d.ts +6 -28
  170. package/dist/recipe-package.d.ts.map +1 -1
  171. package/dist/recipe-package.js +248 -191
  172. package/dist/recipe-package.js.map +1 -1
  173. package/dist/recipe-skills.d.ts.map +1 -1
  174. package/dist/recipe-skills.js +42 -29
  175. package/dist/recipe-skills.js.map +1 -1
  176. package/dist/run-controller.d.ts +10 -9
  177. package/dist/run-controller.d.ts.map +1 -1
  178. package/dist/run-controller.js +28 -21
  179. package/dist/run-controller.js.map +1 -1
  180. package/dist/session.d.ts +40 -53
  181. package/dist/session.d.ts.map +1 -1
  182. package/dist/session.js +312 -173
  183. package/dist/session.js.map +1 -1
  184. package/dist/test-utils.d.ts +7 -7
  185. package/dist/test-utils.d.ts.map +1 -1
  186. package/dist/test-utils.js +32 -15
  187. package/dist/test-utils.js.map +1 -1
  188. package/docs/agent-composition.md +41 -35
  189. package/docs/host-api.md +201 -0
  190. package/docs/index.md +9 -14
  191. package/docs/interactions.md +12 -11
  192. package/docs/mcp-auth.md +6 -6
  193. package/docs/mcp-configuration.md +73 -25
  194. package/docs/pi-extension.md +39 -11
  195. package/docs/recipe-flow.md +9 -9
  196. package/docs/recipe-format.md +106 -41
  197. package/docs/recipe-judges.md +24 -36
  198. package/package.json +23 -17
  199. package/vendor/mcp-client/darwin-arm64/mcp-client +0 -0
  200. package/vendor/mcp-client/darwin-x64/mcp-client +0 -0
  201. package/vendor/mcp-client/linux-arm64/mcp-client +0 -0
  202. package/vendor/recipe-check/darwin-arm64/recipe-check +0 -0
  203. package/vendor/recipe-check/darwin-x64/recipe-check +0 -0
  204. package/vendor/recipe-check/linux-arm64/recipe-check +0 -0
  205. package/vendor/recipe-check/linux-x64/recipe-check +0 -0
  206. package/vendor/recipe-check/linux-x64-musl/recipe-check +0 -0
  207. package/vendor/recipe-check/win32-x64/recipe-check.exe +0 -0
  208. package/dist/agent-tool.d.ts.map +0 -1
  209. package/dist/agent-tool.js.map +0 -1
  210. package/dist/run.d.ts +0 -28
  211. package/dist/run.d.ts.map +0 -1
  212. package/dist/run.js +0 -84
  213. package/dist/run.js.map +0 -1
  214. package/dist/testing.d.ts +0 -25
  215. package/dist/testing.d.ts.map +0 -1
  216. package/dist/testing.js +0 -96
  217. package/dist/testing.js.map +0 -1
  218. package/docs/deployment-configuration.md +0 -65
  219. package/docs/migration.md +0 -70
  220. package/docs/python-bindings-release.md +0 -47
  221. package/docs/recipe-evals.md +0 -70
  222. package/docs/runtime-library.md +0 -171
@@ -2,7 +2,7 @@
2
2
 
3
3
  **Status:** Open format, version 1
4
4
  **Reference implementation:** `@introspection-ai/recipes`
5
- **Validator:** `pi-recipe-check`
5
+ **Validator:** `introspection check`
6
6
 
7
7
  The Recipe Format is a Git-native package contract for complete Pi agents. It
8
8
  defines the agent-owned inputs that a compatible host must interpret the same
@@ -23,7 +23,18 @@ This format does not claim interoperability with non-Pi agent harnesses.
23
23
 
24
24
  ## Package root
25
25
 
26
- A Recipe MUST be a directory containing `package.json`. The manifest MUST have:
26
+ A Recipe MUST be a directory containing `package.json`. At minimum, its
27
+ manifest contains a package name and a `pi` object:
28
+
29
+ ```json
30
+ {
31
+ "name": "acme-research",
32
+ "pi": {}
33
+ }
34
+ ```
35
+
36
+ A fuller package may declare distribution metadata and explicit resource
37
+ paths:
27
38
 
28
39
  ```json
29
40
  {
@@ -39,24 +50,42 @@ A Recipe MUST be a directory containing `package.json`. The manifest MUST have:
39
50
  }
40
51
  ```
41
52
 
42
- `name` is the package identity. `version` is distribution metadata and defaults
43
- to `0.0.0` when omitted for compatibility. `description` is human-facing.
53
+ `name` is the package identity. `version` is optional distribution metadata and
54
+ defaults to `0.0.0` when omitted. `description` is optional human-facing
55
+ metadata. When resource arrays are omitted, conventional `agents/`, `skills/`,
56
+ and `prompts/` directories are discovered when present. Executable extensions
57
+ and MCP servers are never discovered by convention and MUST be declared
58
+ explicitly.
59
+
60
+ Omission and an explicit empty array are different:
61
+
62
+ - an omitted `agents`, `skills`, or `prompts` key opts into its documented
63
+ conventional directory;
64
+ - an explicit `[]` resolves no resources of that kind;
65
+ - every explicitly authored path or glob MUST match.
44
66
 
45
67
  Resource paths:
46
68
 
47
69
  - MUST be relative to the package root;
48
- - MUST NOT traverse outside the package;
70
+ - MUST NOT resolve outside the package, including through symlinks;
49
71
  - MAY be files, directories, or supported glob patterns;
50
- - are resolved deterministically in lexical order.
72
+ - preserve declaration order, with matches inside each glob ordered
73
+ lexically.
51
74
 
52
75
  Unknown top-level `package.json` fields retain normal npm semantics. Unknown
53
76
  Recipe fields inside supported `pi` structures are validation errors unless a
54
77
  later format version explicitly defines them.
55
78
 
79
+ When a Recipe declares non-empty `dependencies` or `optionalDependencies`, it
80
+ MUST commit one supported dependency lockfile: `package-lock.json`,
81
+ `npm-shrinkwrap.json`, `pnpm-lock.yaml`, or `yarn.lock`. npm lockfiles MUST
82
+ carry the same package name and version as `package.json`.
83
+
56
84
  ## Agents
57
85
 
58
- `pi.agents` declares YAML agent definitions. A resolved Recipe MUST contain at
59
- least one agent.
86
+ `pi.agents` may declare YAML agent definitions explicitly. When omitted,
87
+ direct `.yaml` and `.yml` children of `agents/` are discovered. A resolved
88
+ Recipe MUST contain at least one agent.
60
89
 
61
90
  ```yaml
62
91
  name: agent
@@ -67,8 +96,6 @@ model:
67
96
  tools: [read, bash]
68
97
  skills: [research]
69
98
  subagents: [reviewer]
70
- extensions:
71
- include: [citations]
72
99
  system_instructions:
73
100
  mode: append
74
101
  content: Verify every material claim.
@@ -79,19 +106,38 @@ acyclic. Child fields override inherited scalar fields; documented collection
79
106
  fields use the merge or replacement behavior in
80
107
  [Agent composition](agent-composition.md).
81
108
 
82
- Every fully resolved agent MUST define:
109
+ Every agent YAML MUST declare a package-unique lowercase kebab-case `name`.
110
+ This is its
111
+ stable identity for selection, subagent references, artifacts, and telemetry;
112
+ the filename has no semantic meaning.
113
+
114
+ Every fully resolved agent MUST also define `model.name` as
115
+ `<provider>/<model_id>`. The model may be declared directly or inherited with
116
+ `from`.
83
117
 
84
- - `model.name` as `<provider>/<model_id>`;
85
- - `model.thinking_level`;
86
- - `tools`;
87
- - `system_instructions`.
118
+ All remaining agent fields are optional. Omitted `tools`, `skills`, and
119
+ `subagents` resolve to empty lists. Omitted `model.thinking_level` preserves the
120
+ provider or session default. Omitted agent instructions preserve `SYSTEM.md`
121
+ when present, or Pi's normal base prompt otherwise.
88
122
 
89
- Omitted `skills` and `subagents` resolve to empty lists.
123
+ `tools` MUST NOT contain `agent`. The host materializes that session-generated
124
+ tool for a root session whose effective `subagents` list is non-empty.
90
125
 
91
126
  The default agent is named `agent`. If no `agent` exists, a host MAY select the
92
127
  only declared agent. When multiple agents exist without `agent`, the caller
93
128
  MUST select one explicitly.
94
129
 
130
+ ## Judges
131
+
132
+ A Recipe MAY include portable LLM grading definitions as direct `.yaml` or
133
+ `.yml` children of `judges/`. Nested files are not judge sources. Judge names
134
+ MUST be unique within the package.
135
+
136
+ The authored schema, defaults, applicability gates, and model configuration are
137
+ defined in [Recipe judges](recipe-judges.md). The Recipe Format owns this
138
+ declarative evaluation contract; hosts own transcript assembly, execution,
139
+ credentials, retries, persistence, and result processing.
140
+
95
141
  ## Instructions, skills, prompts, and extensions
96
142
 
97
143
  `SYSTEM.md`, when present, is package-wide instruction source. Agent
@@ -99,13 +145,41 @@ MUST select one explicitly.
99
145
  replace the current prompt.
100
146
 
101
147
  Skills follow the [Agent Skills](https://agentskills.io) directory convention
102
- and are selected from the resources declared by `pi.skills`.
103
-
104
- Prompt templates are declared by `pi.prompts`.
105
-
106
- Recipe-owned Pi extensions are declared by `pi.extensions`. An agent MAY select
107
- declared extensions with `extensions.include` and `extensions.exclude`. A host
108
- MUST NOT load undeclared Recipe extension source.
148
+ and are selected from the resources declared by `pi.skills`. A skill is named
149
+ by its `SKILL.md` frontmatter `name`, then by its containing directory; a
150
+ root-level unnamed `SKILL.md` uses the portable fallback name `skill`.
151
+
152
+ Prompt templates are declared by `pi.prompts`. They retain Pi's normal SDK and
153
+ TUI behavior: hosts expose them through `AgentSession.promptTemplates`, and a
154
+ caller invokes one by prompting with its slash command and arguments.
155
+
156
+ Recipe-owned Pi extensions are declared by `pi.extensions`. The deterministically
157
+ resolved set forms the package's executable trust boundary and loads for every
158
+ root and child session. Package membership means execution; agent YAML cannot
159
+ select or remove extensions.
160
+
161
+ An extension declaration may name a module or directory. A directory index
162
+ (`index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mjs`, or `index.cjs`,
163
+ in that precedence order) owns the directory. Without an index, Recipes loads
164
+ its direct extension modules and the indexes of its immediate child
165
+ directories, both in lexical order. Discovery is intentionally shallow;
166
+ declare deeper modules explicitly.
167
+
168
+ Programmatic root and child sessions invoke the closure's factories for their
169
+ own Pi runtime. Interactive Pi keeps one extension runtime for the selected
170
+ Recipe launch and does not retry a partially failed closure without rebuilding
171
+ that runtime. Extension load failures stop the agent before a model call.
172
+ Recipe extensions MUST NOT override host or Pi built-in tool names; use a
173
+ distinct tool name when behavior differs. Extension code retains its non-tool
174
+ behavior even when none of its tools appear in the selected agent's `tools`
175
+ allowlist.
176
+
177
+ The package extension closure is complete with respect to Recipe source, not
178
+ the surrounding host process. A host MAY supply extensions, settings, or other
179
+ runtime policy. Interactive Pi may already have trusted global or project
180
+ resources loaded; compatible hosts MUST keep those additions distinguishable
181
+ from Recipe-owned inputs. `tools` limits model-callable tools, not extension
182
+ hook execution.
109
183
 
110
184
  ## Tools, subagents, and capabilities
111
185
 
@@ -124,19 +198,6 @@ MUST reject an unbound required server before the session begins.
124
198
  See [MCP configuration](mcp-configuration.md) for the complete authored and
125
199
  binding grammar.
126
200
 
127
- ## Quality and resource intent
128
-
129
- Recipe-owned judge YAML expresses portable quality definitions. Hosts MAY use
130
- those definitions online or offline, but MUST preserve their authored identity
131
- and semantics.
132
-
133
- `pi.evals` MAY pin external evaluation suites. The format records the pin; an
134
- evaluation runner remains an external tool.
135
-
136
- Portable resource intent is declared under the documented runtime resource
137
- grammar. A host decides whether it can satisfy that intent and MUST report
138
- unsupported required resources rather than silently weakening them.
139
-
140
201
  ## Host responsibilities
141
202
 
142
203
  The Recipe Format owns:
@@ -144,10 +205,9 @@ The Recipe Format owns:
144
205
  - package and agent interpretation;
145
206
  - instruction composition;
146
207
  - model and tool selection;
147
- - skill, prompt, and extension selection;
208
+ - skill and prompt selection plus the package extension closure;
148
209
  - subagent visibility;
149
210
  - capability policy;
150
- - quality definitions and resource intent.
151
211
 
152
212
  The host owns:
153
213
 
@@ -162,16 +222,21 @@ The host owns:
162
222
 
163
223
  Those host concerns MUST NOT become mandatory Recipe source fields.
164
224
 
225
+ Recipe packages are trusted application code. In particular, authored
226
+ TypeScript extensions execute inside the Pi process with its authority. A host
227
+ that accepts third-party Recipes MUST review or isolate them before execution;
228
+ the format and Host API are not a sandbox boundary.
229
+
165
230
  ## Conformance
166
231
 
167
232
  There are two conformance layers:
168
233
 
169
- 1. `pi-recipe-check` validates authored package snapshots without executing
170
- them.
234
+ 1. A Recipe checker validates authored Recipe source without executing it.
171
235
  2. `@introspection-ai/recipes/test-utils` verifies that a host constructs and
172
236
  disposes Recipe sessions with the required semantics.
173
237
 
174
- A host SHOULD run both layers in CI.
238
+ Pi also runs the same validator automatically whenever it launches with
239
+ `--recipe`. Other hosts SHOULD run both layers in CI.
175
240
 
176
241
  ## Evolution
177
242
 
@@ -10,32 +10,23 @@ my-recipe/
10
10
  ```
11
11
 
12
12
  Nested files such as `judges/calibration/helpful.yaml` are not judge sources.
13
- The standalone `recipe-check` binary, `introspection check`, and in-memory
14
- bindings discover the same direct-child set and return the same validation
15
- result. Recipes without judge sources have no judge diagnostics or
16
- `resources.judges` count.
13
+ `introspection check` discovers this direct-child set. Recipes without judge
14
+ sources have no judge diagnostics.
17
15
 
18
16
  ## Ownership boundary
19
17
 
20
- `pi-recipe-check` owns the portable authored YAML specification and its static,
21
- file-oriented diagnostics. The I/O-free `check_recipe_files` core is the common
22
- validation path used by the filesystem checker, npm CLI, serialized snapshot
23
- API, and Python binding.
24
-
25
- The Introspection judge engine owns runtime evaluation: applicability
26
- execution, conversation assembly and transcript protection, model request
27
- construction, retries, verdict normalization, and evaluation identity. Runtime
28
- implementations should consume or remain explicitly compatible with the
29
- authored specification defined here; new authored fields must land in this
30
- checker and its contract tests rather than being introduced only in a runtime
31
- parser.
32
-
33
- The Rust checker and Python binding return a `Report` containing diagnostics
34
- and, when judges exist, a `resources.judges` source count. The report does not
35
- contain a normalized judge definition, `judge_id`, `definition_hash`, or
36
- registry projection. Migrating project-scoped registry projection away from
37
- the runtime parser is a separate platform change and must not add project or
38
- tenant context to this portable API.
18
+ The validator behind `introspection check` owns the portable authored YAML
19
+ specification and its static, file-oriented diagnostics.
20
+
21
+ Evaluation systems own execution: applicability checks, conversation assembly,
22
+ transcript protection, model requests, retries, verdict normalization, and
23
+ evaluation identity. Implementations should consume or remain explicitly
24
+ compatible with the authored specification defined here. New authored fields
25
+ must land in this checker and its contract tests rather than appearing in only
26
+ one evaluator.
27
+
28
+ Validation reports do not contain normalized judge definitions or
29
+ host-specific registry data.
39
30
 
40
31
  ## Definition shape
41
32
 
@@ -52,8 +43,8 @@ llm:
52
43
  ```
53
44
 
54
45
  `judge`, `instructions`, and `llm.model` are required and non-empty. Judge names
55
- must be unique across all judge files in one recipe. `llm.provider` defaults to
56
- `openai` at runtime.
46
+ must be unique across all judge files in one Recipe. Evaluators default
47
+ `llm.provider` to `openai`.
57
48
 
58
49
  The canonical expanded definition is:
59
50
 
@@ -110,15 +101,15 @@ block is rejected.
110
101
  an environment-variable name, not a credential value.
111
102
 
112
103
  Transport and local settings affect execution but not authored grading
113
- identity. The platform judge engine remains responsible for applying defaults,
114
- building requests, and enforcing runtime routing.
104
+ identity. The evaluator remains responsible for applying defaults, building
105
+ requests, and routing execution.
115
106
 
116
107
  ## Applicability
117
108
 
118
109
  `on` is optional. Omission, an empty mapping, or an empty list makes the judge
119
110
  applicable to every conversation selected for judging. Otherwise it is an
120
111
  OR-list of matchers. Supported events are `message`, `tool`, and `feedback`;
121
- fields within one `match` mapping are ANDed by the runtime engine.
112
+ fields within one `match` mapping are ANDed by the evaluator.
122
113
 
123
114
  ```yaml
124
115
  on:
@@ -138,15 +129,12 @@ on:
138
129
  Match keys are non-empty field paths. Regex literals use Rust regex syntax and
139
130
  support unique `i`, `m`, `s`, and `u` flags. `environment`, `runtime_group`, and
140
131
  paths ending in `pattern_id` are platform-owned and cannot appear as authored
141
- match fields. The runtime engine owns dotted-path traversal and actual gate
142
- evaluation.
132
+ match fields. The evaluator owns dotted-path traversal and gate evaluation.
143
133
 
144
134
  ## Diagnostics
145
135
 
146
- Invalid recipe content is reported through the normal `Report`/`Diagnostic`
147
- model. Judge diagnostics use stable `judge.*` codes, recipe-relative source
148
- paths, useful help text, and deterministic ordering. YAML syntax failures use
136
+ Invalid Recipe content is reported through the normal diagnostics model. Judge
137
+ diagnostics use stable `judge.*` codes, Recipe-relative source paths, useful
138
+ help text, and deterministic ordering. YAML syntax failures use
149
139
  `judge.yaml_malformed` and include a 1-based source span when the parser
150
- provides one. Invalid definitions do not raise a separate content exception in
151
- the Python binding; they return `Report(valid=False, ...)` like other recipe
152
- errors.
140
+ provides one.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@introspection-ai/recipes",
3
- "version": "0.13.0",
3
+ "version": "0.14.1",
4
4
  "description": "The open package format for complete, portable Pi agents.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -10,18 +10,19 @@
10
10
  "files": [
11
11
  "dist",
12
12
  "vendor/mcp-client",
13
+ "vendor/recipe-check",
13
14
  "docs",
14
15
  "README.md",
15
16
  "package.json"
16
17
  ],
17
18
  "repository": {
18
19
  "type": "git",
19
- "url": "git+ssh://git@github.com/introspection-org/pi-recipes.git"
20
+ "url": "git+ssh://git@github.com/introspection-org/recipes.git"
20
21
  },
21
22
  "bugs": {
22
- "url": "https://github.com/introspection-org/pi-recipes/issues"
23
+ "url": "https://github.com/introspection-org/recipes/issues"
23
24
  },
24
- "homepage": "https://github.com/introspection-org/pi-recipes#readme",
25
+ "homepage": "https://github.com/introspection-org/recipes#readme",
25
26
  "publishConfig": {
26
27
  "access": "public",
27
28
  "tag": "latest"
@@ -35,25 +36,29 @@
35
36
  "types": "./dist/interactions.d.ts",
36
37
  "import": "./dist/interactions.js"
37
38
  },
39
+ "./extensions": {
40
+ "types": "./dist/api/extensions.d.ts",
41
+ "import": "./dist/api/extensions.js"
42
+ },
43
+ "./mcp": {
44
+ "types": "./dist/api/mcp.d.ts",
45
+ "import": "./dist/api/mcp.js"
46
+ },
38
47
  "./pi-extension": {
39
48
  "types": "./dist/pi-extension.d.ts",
40
49
  "import": "./dist/pi-extension.js"
41
50
  },
42
- "./pi": {
43
- "types": "./dist/agent-tool.d.ts",
44
- "import": "./dist/agent-tool.js"
51
+ "./agents": {
52
+ "types": "./dist/agents.d.ts",
53
+ "import": "./dist/agents.js"
45
54
  },
46
55
  "./recipe": {
47
56
  "types": "./dist/recipe/resolve.d.ts",
48
57
  "import": "./dist/recipe/resolve.js"
49
58
  },
50
59
  "./session": {
51
- "types": "./dist/session.d.ts",
52
- "import": "./dist/session.js"
53
- },
54
- "./run": {
55
- "types": "./dist/run.d.ts",
56
- "import": "./dist/run.js"
60
+ "types": "./dist/api/session.d.ts",
61
+ "import": "./dist/api/session.js"
57
62
  },
58
63
  "./test-utils": {
59
64
  "types": "./dist/test-utils.d.ts",
@@ -72,6 +77,7 @@
72
77
  "dependencies": {
73
78
  "@introspection-sdk/introspection-pi": "^0.13.0",
74
79
  "@opentelemetry/api": "^1.9.1",
80
+ "ajv": "^8.20.0",
75
81
  "mcporter": "0.12.3",
76
82
  "yaml": "^2.9.0"
77
83
  },
@@ -96,11 +102,11 @@
96
102
  "scripts": {
97
103
  "build": "pnpm build:ts && pnpm build:native",
98
104
  "build:ts": "rm -rf dist && tsc && node scripts/build-mcp-daemon.mjs",
99
- "build:native": "cargo build --release -p pi-mcp-client && node scripts/package-mcp-client.mjs",
105
+ "build:native": "cargo build --release -p pi-mcp-client && cargo build --release -p recipe-check --bin recipe-check && node scripts/package-mcp-client.mjs && node scripts/package-recipe-check.mjs",
100
106
  "bench:mcp-client": "pnpm build:ts && cargo build --release -p pi-mcp-client && node scripts/benchmark-mcp-client.mjs",
101
- "typecheck": "node scripts/check-recipe-check-versions.mjs && tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
102
- "test": "pnpm build:ts && cargo test -p pi-mcp-client -p pi-recipe-check && cargo build -p pi-mcp-client && MCP_CLIENT_BIN=target/debug/mcp-client node scripts/package-mcp-client.mjs && vitest run",
107
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
108
+ "test": "pnpm build:ts && cargo test -p pi-mcp-client -p recipe-check && cargo build -p pi-mcp-client && cargo build -p recipe-check --bin recipe-check && MCP_CLIENT_BIN=target/debug/mcp-client node scripts/package-mcp-client.mjs && vitest run",
103
109
  "pack:check": "pnpm pack --dry-run --json | node scripts/check-npm-pack.mjs",
104
- "clean": "rm -rf dist .turbo node_modules target vendor/mcp-client"
110
+ "clean": "rm -rf dist .turbo node_modules target vendor/mcp-client vendor/recipe-check"
105
111
  }
106
112
  }
@@ -1 +0,0 @@
1
- {"version":3,"file":"agent-tool.d.ts","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGlF,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,WAAW,GACX,QAAQ,GACR,aAAa,GACb,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,eAAe,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,KAAK,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/D,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/D,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChD,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7C;AAyED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,GAAE;IAAE,sBAAsB,CAAC,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;CAAO,GACnE,cAAc,CAuGhB"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"agent-tool.js","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"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"}
package/dist/run.d.ts DELETED
@@ -1,28 +0,0 @@
1
- import type { AgentMessage } from "@earendil-works/pi-agent-core";
2
- import { type CreateRecipeSessionOptions } from "./session.js";
3
- /**
4
- * One turn, no server: create session → single prompt → await settle →
5
- * dispose, always. The programmatic analog of `pi --mode json -p`.
6
- *
7
- * Agent-level failure never throws — it lands in `status: "failed"`. Only
8
- * caller mistakes (bad options, unreadable recipe, missing credentials)
9
- * throw, from session construction.
10
- */
11
- export interface RunRecipeOptions extends CreateRecipeSessionOptions {
12
- prompt: string;
13
- timeoutMs?: number;
14
- signal?: AbortSignal;
15
- /** Session factory; defaults to `createRecipeSession`. Test/DI seam. */
16
- sessionFactory?: (options: CreateRecipeSessionOptions) => Promise<import("./session.js").RecipeSessionHandle>;
17
- }
18
- export interface RecipeRunResult {
19
- status: "finished" | "failed" | "cancelled";
20
- /** Final assistant message text ("" if none). */
21
- text: string;
22
- /** Full transcript, Pi's message shape. */
23
- messages: AgentMessage[];
24
- /** Present iff status === "failed". */
25
- error?: string;
26
- }
27
- export declare function runRecipe(options: RunRecipeOptions): Promise<RecipeRunResult>;
28
- //# sourceMappingURL=run.d.ts.map
package/dist/run.d.ts.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,0BAA0B;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wEAAwE;IACxE,cAAc,CAAC,EAAE,CACf,OAAO,EAAE,0BAA0B,KAChC,OAAO,CAAC,OAAO,cAAc,EAAE,mBAAmB,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC5C,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAmE1B"}
package/dist/run.js DELETED
@@ -1,84 +0,0 @@
1
- import { promptResultText } from "./child-agent.js";
2
- import { createRecipeSession, } from "./session.js";
3
- function lastAssistantStop(messages) {
4
- for (let index = messages.length - 1; index >= 0; index -= 1) {
5
- const message = messages[index];
6
- if (message?.role !== "assistant")
7
- continue;
8
- return {
9
- ...(typeof message.stopReason === "string"
10
- ? { stopReason: message.stopReason }
11
- : {}),
12
- ...(typeof message.errorMessage === "string"
13
- ? { errorMessage: message.errorMessage }
14
- : {}),
15
- };
16
- }
17
- return {};
18
- }
19
- export async function runRecipe(options) {
20
- const { prompt, timeoutMs, signal, sessionFactory, ...sessionOptions } = options;
21
- if (typeof prompt !== "string" || !prompt.trim()) {
22
- throw new TypeError("runRecipe requires a non-empty prompt");
23
- }
24
- if (signal?.aborted) {
25
- return { status: "cancelled", text: "", messages: [] };
26
- }
27
- const handle = await (sessionFactory ?? createRecipeSession)(sessionOptions);
28
- let timedOut = false;
29
- let aborted = false;
30
- let timer;
31
- const onAbort = () => {
32
- aborted = true;
33
- void handle.session.abort().catch(() => { });
34
- };
35
- try {
36
- if (timeoutMs !== undefined) {
37
- timer = setTimeout(() => {
38
- timedOut = true;
39
- void handle.session.abort().catch(() => { });
40
- }, timeoutMs);
41
- }
42
- signal?.addEventListener("abort", onAbort, { once: true });
43
- // The signal may have fired while the asynchronous session factory was
44
- // resolving, before the listener existed.
45
- if (signal?.aborted) {
46
- aborted = true;
47
- await handle.session.abort().catch(() => { });
48
- return {
49
- status: "cancelled",
50
- text: "",
51
- messages: [...handle.session.messages],
52
- };
53
- }
54
- let promptError;
55
- try {
56
- await handle.session.prompt(prompt);
57
- }
58
- catch (err) {
59
- promptError = err instanceof Error ? err.message : String(err);
60
- }
61
- const messages = [...handle.session.messages];
62
- const text = promptResultText({ messages });
63
- const { stopReason, errorMessage } = lastAssistantStop(messages);
64
- if (timedOut || aborted || stopReason === "aborted") {
65
- return { status: "cancelled", text, messages };
66
- }
67
- if (promptError !== undefined || stopReason === "error") {
68
- return {
69
- status: "failed",
70
- text,
71
- messages,
72
- error: promptError ?? errorMessage ?? "agent error",
73
- };
74
- }
75
- return { status: "finished", text, messages };
76
- }
77
- finally {
78
- if (timer !== undefined)
79
- clearTimeout(timer);
80
- signal?.removeEventListener("abort", onAbort);
81
- await handle.dispose();
82
- }
83
- }
84
- //# sourceMappingURL=run.js.map
package/dist/run.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}
package/dist/testing.d.ts DELETED
@@ -1,25 +0,0 @@
1
- import type { ExtensionEvent, ExtensionAPI, RegisteredCommand, ToolDefinition } from "@earendil-works/pi-coding-agent";
2
- export interface MockExtensionAPI extends ExtensionAPI {
3
- commands: Map<string, Omit<RegisteredCommand, "name" | "sourceInfo">>;
4
- tools: Map<string, ToolDefinition<any, any, any>>;
5
- flags: Map<string, {
6
- description?: string;
7
- type: "boolean" | "string";
8
- default?: boolean | string;
9
- }>;
10
- flagValues: Map<string, boolean | string>;
11
- handlers: Map<string, Array<(event: any, ctx: any) => unknown>>;
12
- messages: unknown[];
13
- sentMessages: Array<{
14
- message: any;
15
- options?: any;
16
- }>;
17
- messageRenderers: Map<string, (message: any, options: any, theme: any) => unknown>;
18
- sessionName?: string;
19
- activeTools: string[];
20
- thinkingLevel?: string;
21
- model?: unknown;
22
- emitExtensionEvent(event: ExtensionEvent, ctx: any): Promise<unknown[]>;
23
- }
24
- export declare function createMockExtensionAPI(): MockExtensionAPI;
25
- //# sourceMappingURL=testing.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,iCAAiC,CAAC;AAEzC,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;IACtE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IACrG,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;IAC1C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC;IAChE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IACrD,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzE;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CA8FzD"}