@arke-institute/rhiza 0.1.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 (230) hide show
  1. package/README.md +106 -0
  2. package/dist/__tests__/fixtures/index.d.ts +9 -0
  3. package/dist/__tests__/fixtures/index.d.ts.map +1 -0
  4. package/dist/__tests__/fixtures/index.js +12 -0
  5. package/dist/__tests__/fixtures/index.js.map +1 -0
  6. package/dist/__tests__/fixtures/kladoi/index.d.ts +165 -0
  7. package/dist/__tests__/fixtures/kladoi/index.d.ts.map +1 -0
  8. package/dist/__tests__/fixtures/kladoi/index.js +270 -0
  9. package/dist/__tests__/fixtures/kladoi/index.js.map +1 -0
  10. package/dist/__tests__/fixtures/logs/index.d.ts +19 -0
  11. package/dist/__tests__/fixtures/logs/index.d.ts.map +1 -0
  12. package/dist/__tests__/fixtures/logs/index.js +545 -0
  13. package/dist/__tests__/fixtures/logs/index.js.map +1 -0
  14. package/dist/__tests__/fixtures/mock-client.d.ts +127 -0
  15. package/dist/__tests__/fixtures/mock-client.d.ts.map +1 -0
  16. package/dist/__tests__/fixtures/mock-client.js +415 -0
  17. package/dist/__tests__/fixtures/mock-client.js.map +1 -0
  18. package/dist/__tests__/fixtures/rhizai/index.d.ts +54 -0
  19. package/dist/__tests__/fixtures/rhizai/index.d.ts.map +1 -0
  20. package/dist/__tests__/fixtures/rhizai/index.js +283 -0
  21. package/dist/__tests__/fixtures/rhizai/index.js.map +1 -0
  22. package/dist/__tests__/unit/fixtures.test.d.ts +10 -0
  23. package/dist/__tests__/unit/fixtures.test.d.ts.map +1 -0
  24. package/dist/__tests__/unit/fixtures.test.js +275 -0
  25. package/dist/__tests__/unit/fixtures.test.js.map +1 -0
  26. package/dist/__tests__/unit/handoff/gather.test.d.ts +8 -0
  27. package/dist/__tests__/unit/handoff/gather.test.d.ts.map +1 -0
  28. package/dist/__tests__/unit/handoff/gather.test.js +176 -0
  29. package/dist/__tests__/unit/handoff/gather.test.js.map +1 -0
  30. package/dist/__tests__/unit/handoff/interpret.test.d.ts +9 -0
  31. package/dist/__tests__/unit/handoff/interpret.test.d.ts.map +1 -0
  32. package/dist/__tests__/unit/handoff/interpret.test.js +370 -0
  33. package/dist/__tests__/unit/handoff/interpret.test.js.map +1 -0
  34. package/dist/__tests__/unit/handoff/route.test.d.ts +8 -0
  35. package/dist/__tests__/unit/handoff/route.test.d.ts.map +1 -0
  36. package/dist/__tests__/unit/handoff/route.test.js +271 -0
  37. package/dist/__tests__/unit/handoff/route.test.js.map +1 -0
  38. package/dist/__tests__/unit/handoff/scatter.test.d.ts +7 -0
  39. package/dist/__tests__/unit/handoff/scatter.test.d.ts.map +1 -0
  40. package/dist/__tests__/unit/handoff/scatter.test.js +54 -0
  41. package/dist/__tests__/unit/handoff/scatter.test.js.map +1 -0
  42. package/dist/__tests__/unit/resume.test.d.ts +8 -0
  43. package/dist/__tests__/unit/resume.test.d.ts.map +1 -0
  44. package/dist/__tests__/unit/resume.test.js +134 -0
  45. package/dist/__tests__/unit/resume.test.js.map +1 -0
  46. package/dist/__tests__/unit/status.test.d.ts +8 -0
  47. package/dist/__tests__/unit/status.test.d.ts.map +1 -0
  48. package/dist/__tests__/unit/status.test.js +164 -0
  49. package/dist/__tests__/unit/status.test.js.map +1 -0
  50. package/dist/__tests__/unit/target.test.d.ts +8 -0
  51. package/dist/__tests__/unit/target.test.d.ts.map +1 -0
  52. package/dist/__tests__/unit/target.test.js +116 -0
  53. package/dist/__tests__/unit/target.test.js.map +1 -0
  54. package/dist/__tests__/unit/traverse.test.d.ts +8 -0
  55. package/dist/__tests__/unit/traverse.test.d.ts.map +1 -0
  56. package/dist/__tests__/unit/traverse.test.js +143 -0
  57. package/dist/__tests__/unit/traverse.test.js.map +1 -0
  58. package/dist/__tests__/unit/validation/klados.test.d.ts +16 -0
  59. package/dist/__tests__/unit/validation/klados.test.d.ts.map +1 -0
  60. package/dist/__tests__/unit/validation/klados.test.js +275 -0
  61. package/dist/__tests__/unit/validation/klados.test.js.map +1 -0
  62. package/dist/__tests__/unit/validation/rhiza.test.d.ts +16 -0
  63. package/dist/__tests__/unit/validation/rhiza.test.d.ts.map +1 -0
  64. package/dist/__tests__/unit/validation/rhiza.test.js +612 -0
  65. package/dist/__tests__/unit/validation/rhiza.test.js.map +1 -0
  66. package/dist/__tests__/unit/validation/runtime.test.d.ts +11 -0
  67. package/dist/__tests__/unit/validation/runtime.test.d.ts.map +1 -0
  68. package/dist/__tests__/unit/validation/runtime.test.js +553 -0
  69. package/dist/__tests__/unit/validation/runtime.test.js.map +1 -0
  70. package/dist/__tests__/unit/worker/errors.test.d.ts +2 -0
  71. package/dist/__tests__/unit/worker/errors.test.d.ts.map +1 -0
  72. package/dist/__tests__/unit/worker/errors.test.js +226 -0
  73. package/dist/__tests__/unit/worker/errors.test.js.map +1 -0
  74. package/dist/__tests__/unit/worker/job.test.d.ts +2 -0
  75. package/dist/__tests__/unit/worker/job.test.d.ts.map +1 -0
  76. package/dist/__tests__/unit/worker/job.test.js +233 -0
  77. package/dist/__tests__/unit/worker/job.test.js.map +1 -0
  78. package/dist/client/index.d.ts +10 -0
  79. package/dist/client/index.d.ts.map +1 -0
  80. package/dist/client/index.js +8 -0
  81. package/dist/client/index.js.map +1 -0
  82. package/dist/client/interface.d.ts +142 -0
  83. package/dist/client/interface.d.ts.map +1 -0
  84. package/dist/client/interface.js +8 -0
  85. package/dist/client/interface.js.map +1 -0
  86. package/dist/client/mock.d.ts +95 -0
  87. package/dist/client/mock.d.ts.map +1 -0
  88. package/dist/client/mock.js +795 -0
  89. package/dist/client/mock.js.map +1 -0
  90. package/dist/client/types.d.ts +344 -0
  91. package/dist/client/types.d.ts.map +1 -0
  92. package/dist/client/types.js +8 -0
  93. package/dist/client/types.js.map +1 -0
  94. package/dist/handoff/gather-api.d.ts +60 -0
  95. package/dist/handoff/gather-api.d.ts.map +1 -0
  96. package/dist/handoff/gather-api.js +130 -0
  97. package/dist/handoff/gather-api.js.map +1 -0
  98. package/dist/handoff/gather.d.ts +59 -0
  99. package/dist/handoff/gather.d.ts.map +1 -0
  100. package/dist/handoff/gather.js +134 -0
  101. package/dist/handoff/gather.js.map +1 -0
  102. package/dist/handoff/index.d.ts +19 -0
  103. package/dist/handoff/index.d.ts.map +1 -0
  104. package/dist/handoff/index.js +25 -0
  105. package/dist/handoff/index.js.map +1 -0
  106. package/dist/handoff/interpret.d.ts +79 -0
  107. package/dist/handoff/interpret.d.ts.map +1 -0
  108. package/dist/handoff/interpret.js +197 -0
  109. package/dist/handoff/interpret.js.map +1 -0
  110. package/dist/handoff/invoke.d.ts +82 -0
  111. package/dist/handoff/invoke.d.ts.map +1 -0
  112. package/dist/handoff/invoke.js +196 -0
  113. package/dist/handoff/invoke.js.map +1 -0
  114. package/dist/handoff/route.d.ts +25 -0
  115. package/dist/handoff/route.d.ts.map +1 -0
  116. package/dist/handoff/route.js +65 -0
  117. package/dist/handoff/route.js.map +1 -0
  118. package/dist/handoff/scatter-api.d.ts +62 -0
  119. package/dist/handoff/scatter-api.d.ts.map +1 -0
  120. package/dist/handoff/scatter-api.js +81 -0
  121. package/dist/handoff/scatter-api.js.map +1 -0
  122. package/dist/handoff/scatter.d.ts +19 -0
  123. package/dist/handoff/scatter.d.ts.map +1 -0
  124. package/dist/handoff/scatter.js +27 -0
  125. package/dist/handoff/scatter.js.map +1 -0
  126. package/dist/handoff/target.d.ts +16 -0
  127. package/dist/handoff/target.d.ts.map +1 -0
  128. package/dist/handoff/target.js +51 -0
  129. package/dist/handoff/target.js.map +1 -0
  130. package/dist/index.d.ts +42 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +52 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/logging/index.d.ts +4 -0
  135. package/dist/logging/index.d.ts.map +1 -0
  136. package/dist/logging/index.js +3 -0
  137. package/dist/logging/index.js.map +1 -0
  138. package/dist/logging/logger.d.ts +52 -0
  139. package/dist/logging/logger.d.ts.map +1 -0
  140. package/dist/logging/logger.js +70 -0
  141. package/dist/logging/logger.js.map +1 -0
  142. package/dist/logging/writer.d.ts +63 -0
  143. package/dist/logging/writer.d.ts.map +1 -0
  144. package/dist/logging/writer.js +160 -0
  145. package/dist/logging/writer.js.map +1 -0
  146. package/dist/resume/index.d.ts +77 -0
  147. package/dist/resume/index.d.ts.map +1 -0
  148. package/dist/resume/index.js +110 -0
  149. package/dist/resume/index.js.map +1 -0
  150. package/dist/status/index.d.ts +54 -0
  151. package/dist/status/index.d.ts.map +1 -0
  152. package/dist/status/index.js +107 -0
  153. package/dist/status/index.js.map +1 -0
  154. package/dist/traverse/index.d.ts +53 -0
  155. package/dist/traverse/index.d.ts.map +1 -0
  156. package/dist/traverse/index.js +142 -0
  157. package/dist/traverse/index.js.map +1 -0
  158. package/dist/types/batch.d.ts +53 -0
  159. package/dist/types/batch.d.ts.map +1 -0
  160. package/dist/types/batch.js +2 -0
  161. package/dist/types/batch.js.map +1 -0
  162. package/dist/types/index.d.ts +10 -0
  163. package/dist/types/index.d.ts.map +1 -0
  164. package/dist/types/index.js +2 -0
  165. package/dist/types/index.js.map +1 -0
  166. package/dist/types/klados.d.ts +63 -0
  167. package/dist/types/klados.d.ts.map +1 -0
  168. package/dist/types/klados.js +2 -0
  169. package/dist/types/klados.js.map +1 -0
  170. package/dist/types/log.d.ts +107 -0
  171. package/dist/types/log.d.ts.map +1 -0
  172. package/dist/types/log.js +2 -0
  173. package/dist/types/log.js.map +1 -0
  174. package/dist/types/refs.d.ts +58 -0
  175. package/dist/types/refs.d.ts.map +1 -0
  176. package/dist/types/refs.js +43 -0
  177. package/dist/types/refs.js.map +1 -0
  178. package/dist/types/request.d.ts +69 -0
  179. package/dist/types/request.d.ts.map +1 -0
  180. package/dist/types/request.js +2 -0
  181. package/dist/types/request.js.map +1 -0
  182. package/dist/types/response.d.ts +31 -0
  183. package/dist/types/response.d.ts.map +1 -0
  184. package/dist/types/response.js +2 -0
  185. package/dist/types/response.js.map +1 -0
  186. package/dist/types/rhiza.d.ts +100 -0
  187. package/dist/types/rhiza.d.ts.map +1 -0
  188. package/dist/types/rhiza.js +2 -0
  189. package/dist/types/rhiza.js.map +1 -0
  190. package/dist/types/status.d.ts +84 -0
  191. package/dist/types/status.d.ts.map +1 -0
  192. package/dist/types/status.js +2 -0
  193. package/dist/types/status.js.map +1 -0
  194. package/dist/utils/id.d.ts +15 -0
  195. package/dist/utils/id.d.ts.map +1 -0
  196. package/dist/utils/id.js +25 -0
  197. package/dist/utils/id.js.map +1 -0
  198. package/dist/utils/index.d.ts +2 -0
  199. package/dist/utils/index.d.ts.map +1 -0
  200. package/dist/utils/index.js +2 -0
  201. package/dist/utils/index.js.map +1 -0
  202. package/dist/validation/index.d.ts +9 -0
  203. package/dist/validation/index.d.ts.map +1 -0
  204. package/dist/validation/index.js +9 -0
  205. package/dist/validation/index.js.map +1 -0
  206. package/dist/validation/validate-klados.d.ts +38 -0
  207. package/dist/validation/validate-klados.d.ts.map +1 -0
  208. package/dist/validation/validate-klados.js +139 -0
  209. package/dist/validation/validate-klados.js.map +1 -0
  210. package/dist/validation/validate-rhiza.d.ts +29 -0
  211. package/dist/validation/validate-rhiza.d.ts.map +1 -0
  212. package/dist/validation/validate-rhiza.js +382 -0
  213. package/dist/validation/validate-rhiza.js.map +1 -0
  214. package/dist/validation/validate-runtime.d.ts +28 -0
  215. package/dist/validation/validate-runtime.d.ts.map +1 -0
  216. package/dist/validation/validate-runtime.js +212 -0
  217. package/dist/validation/validate-runtime.js.map +1 -0
  218. package/dist/worker/errors.d.ts +77 -0
  219. package/dist/worker/errors.d.ts.map +1 -0
  220. package/dist/worker/errors.js +143 -0
  221. package/dist/worker/errors.js.map +1 -0
  222. package/dist/worker/index.d.ts +8 -0
  223. package/dist/worker/index.d.ts.map +1 -0
  224. package/dist/worker/index.js +8 -0
  225. package/dist/worker/index.js.map +1 -0
  226. package/dist/worker/job.d.ts +150 -0
  227. package/dist/worker/job.d.ts.map +1 -0
  228. package/dist/worker/job.js +280 -0
  229. package/dist/worker/job.js.map +1 -0
  230. package/package.json +48 -0
@@ -0,0 +1,212 @@
1
+ /**
2
+ * Runtime Validation
3
+ *
4
+ * Validates a rhiza at invoke time by loading all targets and checking:
5
+ * - All targets exist (as klados or rhiza) and are active
6
+ * - Cardinality compatibility
7
+ * - Type compatibility (warnings)
8
+ */
9
+ /**
10
+ * Validate a rhiza at runtime
11
+ *
12
+ * This loads all targets and validates:
13
+ * 1. All targets exist (as klados or rhiza) and are active
14
+ * 2. Cardinality compatibility
15
+ * 3. Type compatibility (warnings)
16
+ */
17
+ export async function validateRhizaRuntime(client, properties) {
18
+ const errors = [];
19
+ const warnings = [];
20
+ const kladoi = new Map();
21
+ const rhizai = new Map();
22
+ // Collect all target IDs from flow
23
+ const targetIds = new Set(Object.keys(properties.flow));
24
+ // Also collect route targets
25
+ for (const step of Object.values(properties.flow)) {
26
+ const routeTargets = extractRouteTargets(step.then);
27
+ for (const target of routeTargets) {
28
+ targetIds.add(target);
29
+ }
30
+ }
31
+ // Load all targets (try as klados first, then as rhiza)
32
+ for (const targetId of targetIds) {
33
+ const resolved = await resolveTarget(client, targetId, errors);
34
+ if (resolved?.type === 'klados') {
35
+ kladoi.set(targetId, resolved.entity);
36
+ }
37
+ else if (resolved?.type === 'rhiza') {
38
+ rhizai.set(targetId, resolved.entity);
39
+ }
40
+ }
41
+ // Skip cardinality/type validation if we're missing targets
42
+ if (errors.length > 0) {
43
+ return { valid: false, errors, warnings, kladoi, rhizai };
44
+ }
45
+ // Validate cardinality compatibility (only for klados targets)
46
+ for (const [kladosId, step] of Object.entries(properties.flow)) {
47
+ validateCardinalityRuntime(kladosId, step.then, kladoi, errors, warnings);
48
+ }
49
+ return {
50
+ valid: errors.length === 0,
51
+ errors,
52
+ warnings,
53
+ kladoi,
54
+ rhizai,
55
+ };
56
+ }
57
+ /**
58
+ * Resolve a target ID to klados or rhiza
59
+ */
60
+ async function resolveTarget(client, targetId, errors) {
61
+ // Try as klados first
62
+ const kladosResult = await client.api.GET('/kladoi/{id}', {
63
+ params: { path: { id: targetId } },
64
+ });
65
+ if (!kladosResult.error && kladosResult.data) {
66
+ const klados = kladosResult.data;
67
+ if (klados.properties.status !== 'active') {
68
+ errors.push({
69
+ code: 'KLADOS_NOT_ACTIVE',
70
+ message: `Klados '${targetId}' is not active (status: ${klados.properties.status})`,
71
+ klados_id: targetId,
72
+ });
73
+ }
74
+ return { type: 'klados', entity: klados };
75
+ }
76
+ // Try as rhiza
77
+ const rhizaResult = await client.api.GET('/rhizai/{id}', {
78
+ params: { path: { id: targetId } },
79
+ });
80
+ if (!rhizaResult.error && rhizaResult.data) {
81
+ const rhiza = rhizaResult.data;
82
+ if (rhiza.properties.status !== 'active') {
83
+ errors.push({
84
+ code: 'RHIZA_NOT_ACTIVE',
85
+ message: `Rhiza '${targetId}' is not active (status: ${rhiza.properties.status})`,
86
+ });
87
+ }
88
+ return { type: 'rhiza', entity: rhiza };
89
+ }
90
+ errors.push({
91
+ code: 'TARGET_NOT_FOUND',
92
+ message: `Target '${targetId}' not found as klados or rhiza`,
93
+ });
94
+ return null;
95
+ }
96
+ /**
97
+ * Extract route targets from a ThenSpec
98
+ */
99
+ function extractRouteTargets(then) {
100
+ if ('done' in then)
101
+ return [];
102
+ const targets = [];
103
+ if ('pass' in then && then.route) {
104
+ targets.push(...then.route.map((r) => r.target));
105
+ }
106
+ if ('scatter' in then && then.route) {
107
+ targets.push(...then.route.map((r) => r.target));
108
+ }
109
+ if ('gather' in then && then.route) {
110
+ targets.push(...then.route.map((r) => r.target));
111
+ }
112
+ return targets;
113
+ }
114
+ /**
115
+ * Validate cardinality at runtime
116
+ */
117
+ function validateCardinalityRuntime(kladosId, then, kladoi, errors, warnings) {
118
+ if ('done' in then) {
119
+ return;
120
+ }
121
+ const sourceKlados = kladoi.get(kladosId);
122
+ if (!sourceKlados)
123
+ return;
124
+ const sourceProduces = sourceKlados.properties.produces;
125
+ if ('scatter' in then) {
126
+ // Scatter requires produces.cardinality === 'many'
127
+ if (sourceProduces.cardinality !== 'many') {
128
+ errors.push({
129
+ code: 'PRODUCER_CARDINALITY_MISMATCH',
130
+ message: `Klados '${kladosId}' uses scatter but produces.cardinality is 'one'`,
131
+ klados_id: kladosId,
132
+ });
133
+ }
134
+ // Scatter target must accept 'one' (if it's a klados)
135
+ const targetKlados = kladoi.get(then.scatter);
136
+ if (targetKlados && targetKlados.properties.accepts.cardinality !== 'one') {
137
+ errors.push({
138
+ code: 'TARGET_CARDINALITY_MISMATCH',
139
+ message: `Scatter target '${then.scatter}' accepts 'many', should accept 'one'`,
140
+ klados_id: kladosId,
141
+ });
142
+ }
143
+ // Check type compatibility (warning)
144
+ if (targetKlados) {
145
+ checkTypeCompatibility(kladosId, sourceProduces.types, targetKlados.properties.accepts.types, warnings);
146
+ }
147
+ }
148
+ if ('gather' in then) {
149
+ // Gather target must accept 'many' (if it's a klados)
150
+ const targetKlados = kladoi.get(then.gather);
151
+ if (targetKlados && targetKlados.properties.accepts.cardinality !== 'many') {
152
+ errors.push({
153
+ code: 'TARGET_CARDINALITY_MISMATCH',
154
+ message: `Gather target '${then.gather}' accepts 'one', should accept 'many'`,
155
+ klados_id: kladosId,
156
+ });
157
+ }
158
+ }
159
+ if ('pass' in then) {
160
+ const targetKlados = kladoi.get(then.pass);
161
+ if (targetKlados) {
162
+ // Cardinality mismatch warning
163
+ if (sourceProduces.cardinality !== targetKlados.properties.accepts.cardinality) {
164
+ warnings.push({
165
+ code: 'CARDINALITY_MISMATCH',
166
+ message: `Klados '${kladosId}' produces '${sourceProduces.cardinality}' but '${then.pass}' accepts '${targetKlados.properties.accepts.cardinality}'`,
167
+ klados_id: kladosId,
168
+ });
169
+ }
170
+ // Type compatibility (warning)
171
+ checkTypeCompatibility(kladosId, sourceProduces.types, targetKlados.properties.accepts.types, warnings);
172
+ }
173
+ }
174
+ }
175
+ /**
176
+ * Check type compatibility (warning only)
177
+ */
178
+ function checkTypeCompatibility(kladosId, produced, accepted, warnings) {
179
+ if (accepted.includes('*'))
180
+ return;
181
+ if (produced.includes('*'))
182
+ return;
183
+ const compatible = produced.some((p) => accepted.some((a) => typeMatches(p, a)));
184
+ if (!compatible) {
185
+ warnings.push({
186
+ code: 'TYPE_MISMATCH',
187
+ message: `Klados '${kladosId}' produces ${JSON.stringify(produced)} but target accepts ${JSON.stringify(accepted)}`,
188
+ klados_id: kladosId,
189
+ });
190
+ }
191
+ }
192
+ /**
193
+ * Check if a type matches a pattern
194
+ */
195
+ function typeMatches(type, pattern) {
196
+ if (pattern === '*')
197
+ return true;
198
+ if (pattern === type)
199
+ return true;
200
+ // Simple glob: "file/*" matches "file/pdf"
201
+ if (pattern.endsWith('/*')) {
202
+ const prefix = pattern.slice(0, -1);
203
+ return type.startsWith(prefix);
204
+ }
205
+ // Check the other direction too (produced pattern matches accepted type)
206
+ if (type.endsWith('/*')) {
207
+ const prefix = type.slice(0, -1);
208
+ return pattern.startsWith(prefix);
209
+ }
210
+ return false;
211
+ }
212
+ //# sourceMappingURL=validate-runtime.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validate-runtime.js","sourceRoot":"","sources":["../../src/validation/validate-runtime.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Klados Error Utilities
3
+ *
4
+ * Standard error codes and helpers for klados error handling.
5
+ */
6
+ import type { ArkeClient } from '@arke-institute/sdk';
7
+ import type { BatchContext } from '../types';
8
+ /**
9
+ * Standard error codes for klados workers
10
+ *
11
+ * Codes are grouped by default retryability:
12
+ * - Retryable: transient issues that may resolve on retry
13
+ * - Non-retryable: permanent failures that won't change on retry
14
+ */
15
+ export declare const KladosErrorCode: {
16
+ readonly NETWORK_ERROR: "NETWORK_ERROR";
17
+ readonly RATE_LIMITED: "RATE_LIMITED";
18
+ readonly TIMEOUT: "TIMEOUT";
19
+ readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
20
+ readonly TEMPORARY_FAILURE: "TEMPORARY_FAILURE";
21
+ readonly NOT_FOUND: "NOT_FOUND";
22
+ readonly VALIDATION_ERROR: "VALIDATION_ERROR";
23
+ readonly PERMISSION_DENIED: "PERMISSION_DENIED";
24
+ readonly INVALID_INPUT: "INVALID_INPUT";
25
+ readonly UNSUPPORTED_TYPE: "UNSUPPORTED_TYPE";
26
+ readonly INTERNAL_ERROR: "INTERNAL_ERROR";
27
+ readonly PROCESSING_ERROR: "PROCESSING_ERROR";
28
+ };
29
+ export type KladosErrorCodeType = (typeof KladosErrorCode)[keyof typeof KladosErrorCode];
30
+ /**
31
+ * Klados error structure
32
+ */
33
+ export interface KladosError {
34
+ code: string;
35
+ message: string;
36
+ retryable: boolean;
37
+ }
38
+ /**
39
+ * Create a KladosError with a standard code
40
+ *
41
+ * @param code - Error code from KladosErrorCode
42
+ * @param message - Human-readable error message
43
+ * @param retryableOverride - Override the default retryability for this code
44
+ */
45
+ export declare function createKladosError(code: KladosErrorCodeType, message: string, retryableOverride?: boolean): KladosError;
46
+ /**
47
+ * Convert an unknown error to a KladosError
48
+ *
49
+ * Attempts to classify common error types automatically.
50
+ */
51
+ export declare function toKladosError(error: unknown): KladosError;
52
+ /**
53
+ * Type guard for KladosError
54
+ */
55
+ export declare function isKladosError(error: unknown): error is KladosError;
56
+ /**
57
+ * Options for failKlados
58
+ */
59
+ export interface FailKladosOptions {
60
+ /** Log file entity ID */
61
+ logFileId: string;
62
+ /** Batch context (if in a scatter/gather) */
63
+ batchContext?: BatchContext;
64
+ /** The error to record */
65
+ error: KladosError | Error | unknown;
66
+ }
67
+ /**
68
+ * Mark a klados job as failed
69
+ *
70
+ * Handles both the log status update AND the batch slot error (if applicable).
71
+ * This is the recommended way to handle errors in klados workers.
72
+ *
73
+ * @param client - Arke client
74
+ * @param options - Failure options
75
+ */
76
+ export declare function failKlados(client: ArkeClient, options: FailKladosOptions): Promise<void>;
77
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/worker/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAI7C;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;CAkBlB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAaD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,iBAAiB,CAAC,EAAE,OAAO,GAC1B,WAAW,CAQb;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAwDzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAWlE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAElB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B,0BAA0B;IAC1B,KAAK,EAAE,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAwBf"}
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Klados Error Utilities
3
+ *
4
+ * Standard error codes and helpers for klados error handling.
5
+ */
6
+ import { updateLogStatus } from '../logging/writer';
7
+ import { errorBatchSlotWithCAS } from '../handoff/gather-api';
8
+ /**
9
+ * Standard error codes for klados workers
10
+ *
11
+ * Codes are grouped by default retryability:
12
+ * - Retryable: transient issues that may resolve on retry
13
+ * - Non-retryable: permanent failures that won't change on retry
14
+ */
15
+ export const KladosErrorCode = {
16
+ // Retryable errors (transient)
17
+ NETWORK_ERROR: 'NETWORK_ERROR',
18
+ RATE_LIMITED: 'RATE_LIMITED',
19
+ TIMEOUT: 'TIMEOUT',
20
+ SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
21
+ TEMPORARY_FAILURE: 'TEMPORARY_FAILURE',
22
+ // Non-retryable errors (permanent)
23
+ NOT_FOUND: 'NOT_FOUND',
24
+ VALIDATION_ERROR: 'VALIDATION_ERROR',
25
+ PERMISSION_DENIED: 'PERMISSION_DENIED',
26
+ INVALID_INPUT: 'INVALID_INPUT',
27
+ UNSUPPORTED_TYPE: 'UNSUPPORTED_TYPE',
28
+ // Unknown/internal
29
+ INTERNAL_ERROR: 'INTERNAL_ERROR',
30
+ PROCESSING_ERROR: 'PROCESSING_ERROR',
31
+ };
32
+ /**
33
+ * Codes that are retryable by default
34
+ */
35
+ const RETRYABLE_CODES = [
36
+ KladosErrorCode.NETWORK_ERROR,
37
+ KladosErrorCode.RATE_LIMITED,
38
+ KladosErrorCode.TIMEOUT,
39
+ KladosErrorCode.SERVICE_UNAVAILABLE,
40
+ KladosErrorCode.TEMPORARY_FAILURE,
41
+ ];
42
+ /**
43
+ * Create a KladosError with a standard code
44
+ *
45
+ * @param code - Error code from KladosErrorCode
46
+ * @param message - Human-readable error message
47
+ * @param retryableOverride - Override the default retryability for this code
48
+ */
49
+ export function createKladosError(code, message, retryableOverride) {
50
+ const defaultRetryable = RETRYABLE_CODES.includes(code);
51
+ return {
52
+ code,
53
+ message,
54
+ retryable: retryableOverride ?? defaultRetryable,
55
+ };
56
+ }
57
+ /**
58
+ * Convert an unknown error to a KladosError
59
+ *
60
+ * Attempts to classify common error types automatically.
61
+ */
62
+ export function toKladosError(error) {
63
+ // Already a KladosError
64
+ if (isKladosError(error)) {
65
+ return error;
66
+ }
67
+ // Standard Error
68
+ if (error instanceof Error) {
69
+ const message = error.message.toLowerCase();
70
+ // Network-related errors
71
+ if (message.includes('network') ||
72
+ message.includes('fetch') ||
73
+ message.includes('econnrefused') ||
74
+ message.includes('enotfound')) {
75
+ return createKladosError(KladosErrorCode.NETWORK_ERROR, error.message);
76
+ }
77
+ // Timeout errors
78
+ if (message.includes('timeout') || message.includes('timed out')) {
79
+ return createKladosError(KladosErrorCode.TIMEOUT, error.message);
80
+ }
81
+ // Rate limiting
82
+ if (message.includes('rate limit') || message.includes('429')) {
83
+ return createKladosError(KladosErrorCode.RATE_LIMITED, error.message);
84
+ }
85
+ // Not found
86
+ if (message.includes('not found') || message.includes('404')) {
87
+ return createKladosError(KladosErrorCode.NOT_FOUND, error.message);
88
+ }
89
+ // Permission errors
90
+ if (message.includes('permission') ||
91
+ message.includes('forbidden') ||
92
+ message.includes('403') ||
93
+ message.includes('unauthorized') ||
94
+ message.includes('401')) {
95
+ return createKladosError(KladosErrorCode.PERMISSION_DENIED, error.message);
96
+ }
97
+ // Default: processing error (retryable to be safe)
98
+ return createKladosError(KladosErrorCode.PROCESSING_ERROR, error.message, true);
99
+ }
100
+ // Unknown type
101
+ return createKladosError(KladosErrorCode.INTERNAL_ERROR, typeof error === 'string' ? error : 'Unknown error', false);
102
+ }
103
+ /**
104
+ * Type guard for KladosError
105
+ */
106
+ export function isKladosError(error) {
107
+ return (typeof error === 'object' &&
108
+ error !== null &&
109
+ 'code' in error &&
110
+ 'message' in error &&
111
+ 'retryable' in error &&
112
+ typeof error.code === 'string' &&
113
+ typeof error.message === 'string' &&
114
+ typeof error.retryable === 'boolean');
115
+ }
116
+ /**
117
+ * Mark a klados job as failed
118
+ *
119
+ * Handles both the log status update AND the batch slot error (if applicable).
120
+ * This is the recommended way to handle errors in klados workers.
121
+ *
122
+ * @param client - Arke client
123
+ * @param options - Failure options
124
+ */
125
+ export async function failKlados(client, options) {
126
+ const kladosError = toKladosError(options.error);
127
+ const logError = {
128
+ code: kladosError.code,
129
+ message: kladosError.message,
130
+ retryable: kladosError.retryable,
131
+ };
132
+ // Update log status
133
+ await updateLogStatus(client, options.logFileId, 'error', logError);
134
+ // Also update batch slot if applicable
135
+ if (options.batchContext) {
136
+ await errorBatchSlotWithCAS(client, options.batchContext.id, options.batchContext.index, {
137
+ code: kladosError.code,
138
+ message: kladosError.message,
139
+ retryable: kladosError.retryable,
140
+ });
141
+ }
142
+ }
143
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/worker/errors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Worker Utilities
3
+ *
4
+ * High-level utilities for building klados workers.
5
+ */
6
+ export { KladosJob, type KladosJobConfig, type KladosJobResult, } from './job';
7
+ export { KladosErrorCode, type KladosErrorCodeType, type KladosError, createKladosError, toKladosError, isKladosError, failKlados, type FailKladosOptions, } from './errors';
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,UAAU,EACV,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Worker Utilities
3
+ *
4
+ * High-level utilities for building klados workers.
5
+ */
6
+ export { KladosJob, } from './job';
7
+ export { KladosErrorCode, createKladosError, toKladosError, isKladosError, failKlados, } from './errors';
8
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,SAAS,GAGV,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,eAAe,EAGf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,UAAU,GAEX,MAAM,UAAU,CAAC"}
@@ -0,0 +1,150 @@
1
+ /**
2
+ * KladosJob - High-level klados job management
3
+ *
4
+ * Manages the full lifecycle of a klados job:
5
+ * - Logging (create, update, finalize)
6
+ * - Error handling (log + batch slot)
7
+ * - Workflow handoff (via interpretThen)
8
+ *
9
+ * Reduces ~80 lines of boilerplate to ~15 lines.
10
+ */
11
+ import { ArkeClient } from '@arke-institute/sdk';
12
+ import type { KladosRequest, KladosResponse, BatchContext } from '../types';
13
+ import { KladosLogger } from '../logging/logger';
14
+ import { type InterpretResult } from '../handoff/interpret';
15
+ /**
16
+ * Configuration for creating a KladosJob
17
+ */
18
+ export interface KladosJobConfig {
19
+ /** Klados agent ID */
20
+ agentId: string;
21
+ /** Klados agent version */
22
+ agentVersion: string;
23
+ /**
24
+ * Authentication token for Arke client.
25
+ * Accepts either:
26
+ * - Agent API key with 'ak_' prefix
27
+ * - User API key with 'uk_' prefix
28
+ * - JWT token from Supabase auth
29
+ */
30
+ authToken?: string;
31
+ }
32
+ /**
33
+ * Result of completing a job
34
+ */
35
+ export interface KladosJobResult {
36
+ /** The handoff result (if in a workflow) */
37
+ handoff?: InterpretResult;
38
+ /** Output entity IDs */
39
+ outputs: string[];
40
+ }
41
+ /**
42
+ * KladosJob - Manages the full lifecycle of a klados job
43
+ *
44
+ * Usage:
45
+ * ```typescript
46
+ * const job = KladosJob.accept(request, { agentId, agentVersion, authToken });
47
+ *
48
+ * ctx.waitUntil(job.run(async () => {
49
+ * job.log.info('Processing...');
50
+ * const outputs = await doWork();
51
+ * return outputs; // Job handles handoff + finalization
52
+ * }));
53
+ *
54
+ * return Response.json(job.acceptResponse);
55
+ * ```
56
+ */
57
+ export declare class KladosJob {
58
+ /** The Arke client */
59
+ readonly client: ArkeClient;
60
+ /** Logger for this job */
61
+ readonly log: KladosLogger;
62
+ /** The original request */
63
+ readonly request: KladosRequest;
64
+ /** The acceptance response to return to caller */
65
+ readonly acceptResponse: KladosResponse;
66
+ /** Job configuration */
67
+ readonly config: KladosJobConfig;
68
+ /** Generated log ID */
69
+ readonly logId: string;
70
+ private state;
71
+ private logFileId;
72
+ private flow;
73
+ /**
74
+ * Create a new KladosJob (private - use static methods)
75
+ */
76
+ private constructor();
77
+ /**
78
+ * Accept a klados request and create a job
79
+ *
80
+ * This is the main factory method. Call this immediately when receiving
81
+ * a request, then process the job asynchronously.
82
+ *
83
+ * @param request - The incoming KladosRequest
84
+ * @param config - Job configuration
85
+ * @returns A new KladosJob instance
86
+ */
87
+ static accept(request: KladosRequest, config: KladosJobConfig): KladosJob;
88
+ /**
89
+ * Get the batch context (if in a scatter/gather)
90
+ */
91
+ get batchContext(): BatchContext | undefined;
92
+ /**
93
+ * Check if this job is part of a workflow
94
+ */
95
+ get isWorkflow(): boolean;
96
+ /**
97
+ * Run the job with automatic lifecycle management
98
+ *
99
+ * This is the recommended way to process a klados job. It handles:
100
+ * - Writing the initial log entry
101
+ * - Catching and recording errors
102
+ * - Executing workflow handoffs
103
+ * - Finalizing the log
104
+ *
105
+ * @param fn - The processing function that returns output entity IDs
106
+ * @returns The job result
107
+ */
108
+ run(fn: () => Promise<string[]>, options?: {
109
+ outputProperties?: Record<string, unknown>;
110
+ }): Promise<KladosJobResult>;
111
+ /**
112
+ * Start the job (write initial log entry)
113
+ *
114
+ * For advanced use cases where you need more control over the lifecycle.
115
+ * Most users should use `run()` instead.
116
+ */
117
+ start(): Promise<void>;
118
+ /**
119
+ * Complete the job with outputs
120
+ *
121
+ * For advanced use cases. Handles workflow handoff and log finalization.
122
+ *
123
+ * @param outputs - Output entity IDs produced by this job
124
+ * @param outputProperties - Properties of the primary output (for routing)
125
+ */
126
+ complete(outputs: string[], outputProperties?: Record<string, unknown>): Promise<KladosJobResult>;
127
+ /**
128
+ * Mark the job as failed
129
+ *
130
+ * Handles both log status update AND batch slot error (if applicable).
131
+ *
132
+ * @param error - The error that caused the failure
133
+ */
134
+ fail(error: unknown): Promise<void>;
135
+ /**
136
+ * Fetch the target entity
137
+ *
138
+ * Convenience method to fetch the entity being processed.
139
+ */
140
+ fetchTarget<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<{
141
+ id: string;
142
+ type: string;
143
+ properties: T;
144
+ }>;
145
+ /**
146
+ * Fetch the rhiza flow definition
147
+ */
148
+ private fetchFlow;
149
+ }
150
+ //# sourceMappingURL=job.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/worker/job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAId,YAAY,EACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI3E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B,wBAAwB;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAOD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAE5B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAE3B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC,uBAAuB;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAGvB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,IAAI,CAAyC;IAErD;;OAEG;IACH,OAAO;IAsBP;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS;IAIzE;;OAEG;IACH,IAAI,YAAY,IAAI,YAAY,GAAG,SAAS,CAE3C;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;OAWG;IACG,GAAG,CACP,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,EAC3B,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACvD,OAAO,CAAC,eAAe,CAAC;IAiB3B;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC5B;;;;;;;OAOG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,EAAE,EACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACzC,OAAO,CAAC,eAAe,CAAC;IA6D3B;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBzC;;;;OAIG;IACG,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QACxF,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,CAAC,CAAC;KACf,CAAC;IAgBF;;OAEG;YACW,SAAS;CAexB"}