@lota-sdk/core 0.4.8 → 0.4.9

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 (259) hide show
  1. package/package.json +11 -12
  2. package/src/ai/embedding-cache.ts +94 -22
  3. package/src/ai-gateway/ai-gateway.ts +738 -223
  4. package/src/config/agent-defaults.ts +176 -75
  5. package/src/config/agent-types.ts +54 -4
  6. package/src/config/constants.ts +8 -2
  7. package/src/config/logger.ts +286 -19
  8. package/src/config/thread-defaults.ts +33 -21
  9. package/src/create-runtime.ts +725 -387
  10. package/src/db/base.service.ts +52 -28
  11. package/src/db/cursor-pagination.ts +71 -30
  12. package/src/db/memory-store.helpers.ts +4 -7
  13. package/src/db/memory-store.ts +856 -598
  14. package/src/db/memory.ts +398 -275
  15. package/src/db/record-id.ts +32 -10
  16. package/src/db/schema-fingerprint.ts +30 -12
  17. package/src/db/service-normalization.ts +255 -0
  18. package/src/db/service.ts +726 -761
  19. package/src/db/startup.ts +140 -66
  20. package/src/db/transaction-conflict.ts +15 -0
  21. package/src/effect/awaitable-effect.ts +87 -0
  22. package/src/effect/errors.ts +121 -0
  23. package/src/effect/helpers.ts +98 -0
  24. package/src/effect/index.ts +22 -0
  25. package/src/effect/layers.ts +228 -0
  26. package/src/effect/runtime-ref.ts +25 -0
  27. package/src/effect/runtime.ts +31 -0
  28. package/src/effect/services.ts +57 -0
  29. package/src/effect/zod.ts +43 -0
  30. package/src/embeddings/provider.ts +122 -76
  31. package/src/index.ts +46 -1
  32. package/src/openrouter/direct-provider.ts +11 -35
  33. package/src/queues/autonomous-job.queue.ts +130 -74
  34. package/src/queues/context-compaction.queue.ts +60 -15
  35. package/src/queues/delayed-node-promotion.queue.ts +52 -15
  36. package/src/queues/document-processor.queue.ts +52 -77
  37. package/src/queues/memory-consolidation.queue.ts +47 -32
  38. package/src/queues/organization-learning.queue.ts +13 -4
  39. package/src/queues/plan-agent-heartbeat.queue.ts +65 -21
  40. package/src/queues/plan-scheduler.queue.ts +107 -31
  41. package/src/queues/post-chat-memory.queue.ts +66 -24
  42. package/src/queues/queue-factory.ts +142 -52
  43. package/src/queues/standalone-worker.ts +39 -0
  44. package/src/queues/title-generation.queue.ts +54 -9
  45. package/src/redis/connection.ts +84 -32
  46. package/src/redis/index.ts +6 -8
  47. package/src/redis/org-memory-lock.ts +60 -27
  48. package/src/redis/redis-lease-lock.ts +200 -121
  49. package/src/redis/runtime-connection.ts +10 -0
  50. package/src/redis/stream-context.ts +84 -46
  51. package/src/runtime/agent-identity-overrides.ts +2 -2
  52. package/src/runtime/agent-runtime-policy.ts +4 -1
  53. package/src/runtime/agent-stream-helpers.ts +20 -9
  54. package/src/runtime/chat-run-orchestration.ts +102 -19
  55. package/src/runtime/chat-run-registry.ts +36 -2
  56. package/src/runtime/context-compaction/context-compaction-runtime.ts +107 -0
  57. package/src/runtime/{context-compaction.ts → context-compaction/context-compaction.ts} +114 -91
  58. package/src/runtime/execution-plan-visibility.ts +2 -2
  59. package/src/runtime/execution-plan.ts +42 -15
  60. package/src/runtime/graph-designer.ts +11 -7
  61. package/src/runtime/helper-model.ts +135 -48
  62. package/src/runtime/index.ts +7 -7
  63. package/src/runtime/indexed-repositories-policy.ts +3 -3
  64. package/src/runtime/{memory-block.ts → memory/memory-block.ts} +40 -36
  65. package/src/runtime/{memory-digest-policy.ts → memory/memory-digest-policy.ts} +1 -1
  66. package/src/runtime/{memory-pipeline.ts → memory/memory-pipeline.ts} +1 -1
  67. package/src/runtime/{memory-prompts-fact.ts → memory/memory-prompts-fact.ts} +2 -2
  68. package/src/runtime/{memory-scope.ts → memory/memory-scope.ts} +12 -6
  69. package/src/runtime/plugin-resolution.ts +144 -24
  70. package/src/runtime/plugin-types.ts +9 -1
  71. package/src/runtime/post-turn-side-effects.ts +197 -130
  72. package/src/runtime/retrieval-adapters.ts +38 -4
  73. package/src/runtime/runtime-config.ts +150 -61
  74. package/src/runtime/runtime-extensions.ts +21 -34
  75. package/src/runtime/social-chat/social-chat-agent-runner.ts +157 -0
  76. package/src/runtime/{social-chat-history.ts → social-chat/social-chat-history.ts} +42 -20
  77. package/src/runtime/social-chat/social-chat.ts +594 -0
  78. package/src/runtime/specialist-runner.ts +36 -10
  79. package/src/runtime/team-consultation/team-consultation-orchestrator.ts +427 -0
  80. package/src/runtime/{team-consultation-prompts.ts → team-consultation/team-consultation-prompts.ts} +6 -2
  81. package/src/runtime/thread-chat-helpers.ts +2 -2
  82. package/src/runtime/thread-plan-turn.ts +2 -1
  83. package/src/runtime/thread-turn-context.ts +172 -94
  84. package/src/runtime/turn-lifecycle.ts +93 -27
  85. package/src/services/agent-activity.service.ts +287 -203
  86. package/src/services/agent-executor.service.ts +329 -217
  87. package/src/services/artifact.service.ts +225 -148
  88. package/src/services/attachment.service.ts +137 -115
  89. package/src/services/autonomous-job.service.ts +888 -491
  90. package/src/services/chat-run-registry.service.ts +11 -1
  91. package/src/services/context-compaction.service.ts +136 -86
  92. package/src/services/document-chunk.service.ts +162 -90
  93. package/src/services/execution-plan/execution-plan-approval.ts +26 -0
  94. package/src/services/execution-plan/execution-plan-context.ts +29 -0
  95. package/src/services/execution-plan/execution-plan-graph.ts +256 -0
  96. package/src/services/execution-plan/execution-plan-schedule.ts +84 -0
  97. package/src/services/execution-plan/execution-plan-spec.ts +75 -0
  98. package/src/services/execution-plan/execution-plan.service.ts +1041 -0
  99. package/src/services/feedback-loop.service.ts +132 -76
  100. package/src/services/global-orchestrator.service.ts +80 -170
  101. package/src/services/graph-full-routing.ts +182 -0
  102. package/src/services/index.ts +18 -21
  103. package/src/services/institutional-memory.service.ts +220 -123
  104. package/src/services/learned-skill.service.ts +364 -259
  105. package/src/services/memory/memory-conversation.ts +95 -0
  106. package/src/services/memory/memory-org-memory.ts +39 -0
  107. package/src/services/memory/memory-preseeded.ts +80 -0
  108. package/src/services/memory/memory-rerank.ts +297 -0
  109. package/src/services/{memory-utils.ts → memory/memory-utils.ts} +5 -5
  110. package/src/services/memory/memory.service.ts +692 -0
  111. package/src/services/memory/rerank.service.ts +209 -0
  112. package/src/services/monitoring-window.service.ts +92 -70
  113. package/src/services/mutating-approval.service.ts +62 -53
  114. package/src/services/node-workspace.service.ts +141 -98
  115. package/src/services/notification.service.ts +17 -16
  116. package/src/services/organization-member.service.ts +120 -66
  117. package/src/services/organization.service.ts +144 -51
  118. package/src/services/ownership-dispatcher.service.ts +415 -264
  119. package/src/services/plan/plan-agent-heartbeat.service.ts +234 -0
  120. package/src/services/plan/plan-agent-query.service.ts +322 -0
  121. package/src/services/plan/plan-approval.service.ts +102 -0
  122. package/src/services/plan/plan-artifact.service.ts +60 -0
  123. package/src/services/plan/plan-builder.service.ts +76 -0
  124. package/src/services/plan/plan-checkpoint.service.ts +103 -0
  125. package/src/services/{plan-compiler.service.ts → plan/plan-compiler.service.ts} +26 -9
  126. package/src/services/plan/plan-completion-side-effects.ts +175 -0
  127. package/src/services/plan/plan-coordination.service.ts +181 -0
  128. package/src/services/plan/plan-cycle.service.ts +398 -0
  129. package/src/services/plan/plan-deadline.service.ts +547 -0
  130. package/src/services/plan/plan-event-delivery.service.ts +261 -0
  131. package/src/services/plan/plan-executor-context.ts +35 -0
  132. package/src/services/plan/plan-executor-graph.ts +475 -0
  133. package/src/services/plan/plan-executor-helpers.ts +322 -0
  134. package/src/services/plan/plan-executor-persistence.ts +209 -0
  135. package/src/services/plan/plan-executor.service.ts +1654 -0
  136. package/src/services/{plan-helpers.ts → plan/plan-helpers.ts} +1 -1
  137. package/src/services/{plan-run-data.ts → plan/plan-run-data.ts} +4 -4
  138. package/src/services/plan/plan-run-serialization.ts +15 -0
  139. package/src/services/plan/plan-run.service.ts +644 -0
  140. package/src/services/plan/plan-scheduler.service.ts +385 -0
  141. package/src/services/plan/plan-template.service.ts +224 -0
  142. package/src/services/plan/plan-transaction-events.ts +33 -0
  143. package/src/services/plan/plan-validator.service.ts +907 -0
  144. package/src/services/plan/plan-workspace.service.ts +125 -0
  145. package/src/services/plugin-executor.service.ts +97 -68
  146. package/src/services/quality-metrics.service.ts +112 -94
  147. package/src/services/queue-job.service.ts +296 -230
  148. package/src/services/recent-activity-title.service.ts +65 -36
  149. package/src/services/recent-activity.service.ts +274 -259
  150. package/src/services/skill-resolver.service.ts +38 -12
  151. package/src/services/social-chat-history.service.ts +176 -125
  152. package/src/services/system-executor.service.ts +91 -61
  153. package/src/services/thread/thread-active-run.ts +203 -0
  154. package/src/services/thread/thread-bootstrap.ts +369 -0
  155. package/src/services/thread/thread-listing.ts +198 -0
  156. package/src/services/thread/thread-memory-block.ts +117 -0
  157. package/src/services/thread/thread-message.service.ts +363 -0
  158. package/src/services/thread/thread-record-store.ts +155 -0
  159. package/src/services/thread/thread-title.service.ts +74 -0
  160. package/src/services/thread/thread-turn-execution.ts +280 -0
  161. package/src/services/thread/thread-turn-message-context.ts +73 -0
  162. package/src/services/thread/thread-turn-preparation.service.ts +1146 -0
  163. package/src/services/thread/thread-turn-streaming.ts +402 -0
  164. package/src/services/thread/thread-turn-tracing.ts +35 -0
  165. package/src/services/thread/thread-turn.ts +343 -0
  166. package/src/services/thread/thread.service.ts +335 -0
  167. package/src/services/user.service.ts +82 -32
  168. package/src/services/write-intent-validator.service.ts +63 -51
  169. package/src/storage/attachment-parser.ts +69 -27
  170. package/src/storage/attachment-storage.service.ts +331 -275
  171. package/src/storage/generated-document-storage.service.ts +66 -34
  172. package/src/system-agents/agent-result.ts +3 -1
  173. package/src/system-agents/context-compaction.agent.ts +2 -2
  174. package/src/system-agents/delegated-agent-factory.ts +159 -90
  175. package/src/system-agents/memory-reranker.agent.ts +2 -2
  176. package/src/system-agents/memory.agent.ts +2 -2
  177. package/src/system-agents/recent-activity-title-refiner.agent.ts +2 -2
  178. package/src/system-agents/regular-chat-memory-digest.agent.ts +2 -2
  179. package/src/system-agents/skill-extractor.agent.ts +2 -2
  180. package/src/system-agents/skill-manager.agent.ts +2 -2
  181. package/src/system-agents/thread-router.agent.ts +157 -113
  182. package/src/system-agents/title-generator.agent.ts +2 -2
  183. package/src/tools/execution-plan.tool.ts +220 -161
  184. package/src/tools/fetch-webpage.tool.ts +21 -17
  185. package/src/tools/firecrawl-client.ts +16 -6
  186. package/src/tools/index.ts +1 -0
  187. package/src/tools/memory-block.tool.ts +14 -6
  188. package/src/tools/plan-approval.tool.ts +49 -47
  189. package/src/tools/read-file-parts.tool.ts +44 -33
  190. package/src/tools/remember-memory.tool.ts +65 -45
  191. package/src/tools/search-web.tool.ts +26 -22
  192. package/src/tools/search.tool.ts +41 -29
  193. package/src/tools/team-think.tool.ts +124 -83
  194. package/src/tools/user-questions.tool.ts +4 -3
  195. package/src/tools/web-tool-shared.ts +6 -0
  196. package/src/utils/async.ts +17 -23
  197. package/src/utils/crypto.ts +21 -0
  198. package/src/utils/date-time.ts +40 -1
  199. package/src/utils/errors.ts +95 -16
  200. package/src/utils/hono-error-handler.ts +24 -39
  201. package/src/utils/index.ts +2 -1
  202. package/src/utils/null-proto-record.ts +41 -0
  203. package/src/utils/sse-keepalive.ts +124 -21
  204. package/src/workers/bootstrap.ts +186 -51
  205. package/src/workers/memory-consolidation.worker.ts +325 -237
  206. package/src/workers/organization-learning.worker.ts +50 -16
  207. package/src/workers/regular-chat-memory-digest.helpers.ts +28 -27
  208. package/src/workers/regular-chat-memory-digest.runner.ts +175 -114
  209. package/src/workers/skill-extraction.runner.ts +176 -93
  210. package/src/workers/utils/file-section-chunker.ts +8 -10
  211. package/src/workers/utils/repo-structure-extractor.ts +349 -260
  212. package/src/workers/utils/repomix-file-sections.ts +2 -2
  213. package/src/workers/utils/thread-message-query.ts +97 -38
  214. package/src/workers/worker-utils.ts +56 -31
  215. package/src/config/debug-logger.ts +0 -47
  216. package/src/redis/connection-accessor.ts +0 -26
  217. package/src/runtime/context-compaction-runtime.ts +0 -87
  218. package/src/runtime/social-chat-agent-runner.ts +0 -118
  219. package/src/runtime/social-chat.ts +0 -516
  220. package/src/runtime/team-consultation-orchestrator.ts +0 -272
  221. package/src/services/adaptive-playbook.service.ts +0 -152
  222. package/src/services/artifact-provenance.service.ts +0 -172
  223. package/src/services/chat-attachments.service.ts +0 -17
  224. package/src/services/context-compaction-runtime.singleton.ts +0 -13
  225. package/src/services/execution-plan.service.ts +0 -1118
  226. package/src/services/memory.service.ts +0 -914
  227. package/src/services/plan-agent-heartbeat.service.ts +0 -136
  228. package/src/services/plan-agent-query.service.ts +0 -267
  229. package/src/services/plan-approval.service.ts +0 -83
  230. package/src/services/plan-artifact.service.ts +0 -50
  231. package/src/services/plan-builder.service.ts +0 -67
  232. package/src/services/plan-checkpoint.service.ts +0 -81
  233. package/src/services/plan-completion-side-effects.ts +0 -80
  234. package/src/services/plan-coordination.service.ts +0 -157
  235. package/src/services/plan-cycle.service.ts +0 -284
  236. package/src/services/plan-deadline.service.ts +0 -430
  237. package/src/services/plan-event-delivery.service.ts +0 -166
  238. package/src/services/plan-executor.service.ts +0 -1950
  239. package/src/services/plan-run.service.ts +0 -515
  240. package/src/services/plan-scheduler.service.ts +0 -240
  241. package/src/services/plan-template.service.ts +0 -177
  242. package/src/services/plan-validator.service.ts +0 -818
  243. package/src/services/plan-workspace.service.ts +0 -83
  244. package/src/services/rerank.service.ts +0 -156
  245. package/src/services/thread-message.service.ts +0 -275
  246. package/src/services/thread-plan-registry.service.ts +0 -22
  247. package/src/services/thread-title.service.ts +0 -39
  248. package/src/services/thread-turn-preparation.service.ts +0 -1147
  249. package/src/services/thread-turn.ts +0 -172
  250. package/src/services/thread.service.ts +0 -869
  251. package/src/utils/env.ts +0 -8
  252. /package/src/runtime/{context-compaction-constants.ts → context-compaction/context-compaction-constants.ts} +0 -0
  253. /package/src/runtime/{memory-format.ts → memory/memory-format.ts} +0 -0
  254. /package/src/runtime/{memory-prompts-parse.ts → memory/memory-prompts-parse.ts} +0 -0
  255. /package/src/runtime/{memory-prompts-update.ts → memory/memory-prompts-update.ts} +0 -0
  256. /package/src/runtime/{social-chat-prompts.ts → social-chat/social-chat-prompts.ts} +0 -0
  257. /package/src/services/{plan-node-spec.ts → plan/plan-node-spec.ts} +0 -0
  258. /package/src/services/{thread-constants.ts → thread/thread-constants.ts} +0 -0
  259. /package/src/services/{thread.types.ts → thread/thread.types.ts} +0 -0
@@ -1,6 +1,8 @@
1
1
  import { S3Client } from 'bun'
2
+ import { Context, Schema, Effect, Layer } from 'effect'
2
3
 
3
- import { getRuntimeConfig } from '../runtime/runtime-config'
4
+ import { RuntimeConfigServiceTag } from '../effect/services'
5
+ import type { ResolvedLotaRuntimeConfig } from '../runtime/runtime-config'
4
6
  import { toSafeSegment } from './attachment-utils'
5
7
 
6
8
  function toSafePathSegment(value: string): string {
@@ -23,43 +25,73 @@ function buildGeneratedDocumentStorageKey(params: {
23
25
  return `${safeOrganizationId}/generated/${safeNamespace}/${safeRelativePath}`
24
26
  }
25
27
 
26
- class GeneratedDocumentStorageService {
27
- private _client: InstanceType<typeof S3Client> | undefined
28
+ class GeneratedDocumentStorageError extends Schema.TaggedErrorClass<GeneratedDocumentStorageError>()(
29
+ 'GeneratedDocumentStorageError',
30
+ { message: Schema.String, cause: Schema.Defect },
31
+ ) {}
28
32
 
29
- private get client(): InstanceType<typeof S3Client> {
30
- if (!this._client) {
31
- const config = getRuntimeConfig()
32
- this._client = new S3Client({
33
- accessKeyId: config.s3.accessKeyId,
34
- secretAccessKey: config.s3.secretAccessKey,
35
- bucket: config.s3.bucket,
36
- endpoint: config.s3.endpoint,
37
- region: config.s3.region,
38
- })
39
- }
40
- return this._client
41
- }
33
+ export function makeGeneratedDocumentStorageService(config: ResolvedLotaRuntimeConfig) {
34
+ const client = new S3Client({
35
+ accessKeyId: config.s3.accessKeyId,
36
+ secretAccessKey: config.s3.secretAccessKey,
37
+ bucket: config.s3.bucket,
38
+ endpoint: config.s3.endpoint,
39
+ region: config.s3.region,
40
+ })
42
41
 
43
- async writeTextArtifact(params: {
44
- organizationId: string
45
- namespace: string
46
- relativePath: string
47
- content: string
48
- mediaType: string
49
- }): Promise<{ storageKey: string; sizeBytes: number }> {
50
- const storageKey = buildGeneratedDocumentStorageKey(params)
51
- const sizeBytes = Buffer.byteLength(params.content, 'utf8')
52
- await this.client.file(storageKey).write(params.content, { type: params.mediaType })
53
- return { storageKey, sizeBytes }
54
- }
42
+ return {
43
+ writeTextArtifact(params: {
44
+ organizationId: string
45
+ namespace: string
46
+ relativePath: string
47
+ content: string
48
+ mediaType: string
49
+ }) {
50
+ const storageKey = buildGeneratedDocumentStorageKey(params)
51
+ const sizeBytes = Buffer.byteLength(params.content, 'utf8')
52
+ return Effect.tryPromise({
53
+ try: () => client.file(storageKey).write(params.content, { type: params.mediaType }),
54
+ catch: (cause) =>
55
+ new GeneratedDocumentStorageError({
56
+ message: `Failed to write generated document artifact ${storageKey}.`,
57
+ cause,
58
+ }),
59
+ }).pipe(Effect.as({ storageKey, sizeBytes }))
60
+ },
55
61
 
56
- async readTextArtifact(storageKey: string): Promise<string> {
57
- return await this.client.file(storageKey).text()
58
- }
62
+ readTextArtifact(storageKey: string) {
63
+ return Effect.tryPromise({
64
+ try: () => client.file(storageKey).text(),
65
+ catch: (cause) =>
66
+ new GeneratedDocumentStorageError({
67
+ message: `Failed to read generated document artifact ${storageKey}.`,
68
+ cause,
69
+ }),
70
+ })
71
+ },
59
72
 
60
- async deleteTextArtifact(storageKey: string): Promise<void> {
61
- await this.client.file(storageKey).delete()
73
+ deleteTextArtifact(storageKey: string) {
74
+ return Effect.tryPromise({
75
+ try: () => client.file(storageKey).delete(),
76
+ catch: (cause) =>
77
+ new GeneratedDocumentStorageError({
78
+ message: `Failed to delete generated document artifact ${storageKey}.`,
79
+ cause,
80
+ }),
81
+ }).pipe(Effect.asVoid)
82
+ },
62
83
  }
63
84
  }
64
85
 
65
- export const generatedDocumentStorageService = new GeneratedDocumentStorageService()
86
+ export class GeneratedDocumentStorageServiceTag extends Context.Service<
87
+ GeneratedDocumentStorageServiceTag,
88
+ ReturnType<typeof makeGeneratedDocumentStorageService>
89
+ >()('GeneratedDocumentStorageService') {}
90
+
91
+ export const GeneratedDocumentStorageServiceLive = Layer.effect(
92
+ GeneratedDocumentStorageServiceTag,
93
+ Effect.gen(function* () {
94
+ const config = yield* RuntimeConfigServiceTag
95
+ return makeGeneratedDocumentStorageService(config)
96
+ }),
97
+ )
@@ -1,3 +1,5 @@
1
+ import { ValidationError } from '../effect/errors'
2
+
1
3
  const SUBSTANTIVE_CHAR_PATTERN = /[\p{L}\p{N}]/u
2
4
  const WORD_LIKE_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}/._'-]*/gu
3
5
 
@@ -20,7 +22,7 @@ function isSubstantiveAgentResult(value: string): boolean {
20
22
  export function assertSubstantiveAgentResult(value: string, label = 'Agent result'): string {
21
23
  const normalized = normalizeAgentResultText(value)
22
24
  if (!isSubstantiveAgentResult(normalized)) {
23
- throw new Error(`${label} must contain substantive text.`)
25
+ throw new ValidationError({ message: `${label} must contain substantive text.` })
24
26
  }
25
27
 
26
28
  return normalized
@@ -1,6 +1,6 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
 
3
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
3
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
4
4
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
5
5
  import {
6
6
  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -34,7 +34,7 @@ The caller enforces a structured output schema with exactly one field:
34
34
  export function createContextCompactionAgent(options: CreateHelperToolLoopAgentOptions) {
35
35
  return new ToolLoopAgent({
36
36
  id: 'context-compaction',
37
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
37
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
38
38
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
39
39
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
40
40
  ...resolveHelperAgentOptions(options, { instructions: CONTEXT_COMPACTION_PROMPT }),
@@ -1,10 +1,12 @@
1
- import { ToolLoopAgent, stepCountIs, tool } from 'ai'
1
+ import { generateText, ToolLoopAgent, stepCountIs, tool } from 'ai'
2
2
  import type { ModelMessage, LanguageModel, ToolLoopAgentSettings, ToolSet } from 'ai'
3
+ import { Schema, Effect } from 'effect'
3
4
  import { z } from 'zod'
4
5
 
5
6
  import type { ToolDefinition } from '../ai/definitions'
6
7
  import { aiLogger } from '../config/logger'
7
- import { formatUtcPromptDate } from '../utils/date-time'
8
+ import { formatUtcPromptDate, nowDate } from '../utils/date-time'
9
+ import { getErrorMessage } from '../utils/errors'
8
10
  import { isRecord } from '../utils/string'
9
11
  import { assertSubstantiveAgentResult } from './agent-result'
10
12
 
@@ -28,11 +30,26 @@ interface DelegatedAgentDefinitionWithContext<TContext> extends Omit<DelegatedAg
28
30
  createTools: (context: TContext) => ToolSet
29
31
  }
30
32
 
33
+ class DelegatedAgentError extends Schema.TaggedErrorClass<DelegatedAgentError>()('DelegatedAgentError', {
34
+ stage: Schema.Literals(['generate', 'validate', 'follow-up-generate', 'follow-up-validate']),
35
+ label: Schema.String,
36
+ message: Schema.String,
37
+ cause: Schema.Defect,
38
+ }) {}
39
+
40
+ function toDelegatedAgentError(
41
+ stage: DelegatedAgentError['stage'],
42
+ label: string,
43
+ cause: unknown,
44
+ ): DelegatedAgentError {
45
+ return new DelegatedAgentError({ stage, label, message: getErrorMessage(cause), cause })
46
+ }
47
+
31
48
  function resolveAgentModel(model: AgentModel): LanguageModel {
32
49
  return typeof model === 'function' ? model() : model
33
50
  }
34
51
 
35
- function buildCurrentDateContext(now = new Date()): string {
52
+ function buildCurrentDateContext(now = nowDate()): string {
36
53
  return [`Today is ${formatUtcPromptDate(now)}.`, 'Use this exact date for any recency reasoning.'].join(' ')
37
54
  }
38
55
 
@@ -134,49 +151,71 @@ function extractToolResultText(messages: ModelMessage[]): string {
134
151
  return chunks.join('\n\n---\n\n')
135
152
  }
136
153
 
137
- async function generateSubstantiveDelegatedAgentResult(params: {
154
+ export function generateSubstantiveDelegatedAgentResultEffect(params: {
138
155
  label: string
139
156
  task: string
140
157
  abortSignal?: AbortSignal
141
158
  createAgent: () => ToolLoopAgent<never, ToolSet>
142
- }): Promise<string> {
143
- const agent = params.createAgent()
144
- const result = await agent.generate({ prompt: params.task, abortSignal: params.abortSignal })
145
-
146
- try {
147
- return assertSubstantiveAgentResult(result.text, params.label)
148
- } catch (firstError) {
149
- aiLogger.warn`Delegated agent returned non-substantive result, attempting follow-up synthesis (label=${params.label}, textLength=${result.text.length})`
150
-
151
- if (params.abortSignal?.aborted) {
152
- throw firstError
153
- }
159
+ synthesize: (prompt: string, abortSignal?: AbortSignal) => PromiseLike<{ text: string }>
160
+ }): Effect.Effect<string, DelegatedAgentError> {
161
+ return Effect.gen(function* () {
162
+ const agent = params.createAgent()
163
+ const result = yield* Effect.tryPromise({
164
+ try: () => agent.generate({ prompt: params.task, abortSignal: params.abortSignal }),
165
+ catch: (error) => toDelegatedAgentError('generate', params.label, error),
166
+ })
167
+
168
+ return yield* Effect.try({
169
+ try: () => assertSubstantiveAgentResult(result.text, params.label),
170
+ catch: (error) => toDelegatedAgentError('validate', params.label, error),
171
+ }).pipe(
172
+ Effect.catch((firstError) =>
173
+ Effect.gen(function* () {
174
+ yield* Effect.sync(() => {
175
+ aiLogger.warn`Delegated agent returned non-substantive result, attempting follow-up synthesis (label=${params.label}, textLength=${result.text.length})`
176
+ })
177
+
178
+ if (params.abortSignal?.aborted) {
179
+ return yield* firstError
180
+ }
154
181
 
155
- // Try a follow-up: feed the agent's tool results back as context and ask for synthesis
156
- const toolContext = extractToolResultText('messages' in result ? ((result.messages ?? []) as ModelMessage[]) : [])
157
- if (toolContext.length > 100) {
158
- const followUpPrompt = [
159
- params.task,
160
- '',
161
- 'Here is the research data you already gathered:',
162
- '',
163
- toolContext.slice(0, 8000),
164
- '',
165
- NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT,
166
- ].join('\n')
167
-
168
- const followUp = await params.createAgent().generate({ prompt: followUpPrompt, abortSignal: params.abortSignal })
169
-
170
- try {
171
- return assertSubstantiveAgentResult(followUp.text, params.label)
172
- } catch (secondError) {
173
- aiLogger.error`Delegated agent follow-up also non-substantive (label=${params.label}, textLength=${followUp.text.length}, textPreview=${followUp.text.slice(0, 200)})`
174
- throw secondError
175
- }
176
- }
182
+ // Try a follow-up: feed the agent's tool results back as context and ask for synthesis
183
+ const toolContext = extractToolResultText(
184
+ 'messages' in result ? ((result.messages ?? []) as ModelMessage[]) : [],
185
+ )
186
+ if (toolContext.length <= 100) {
187
+ return yield* firstError
188
+ }
177
189
 
178
- throw firstError
179
- }
190
+ const followUpPrompt = [
191
+ params.task,
192
+ '',
193
+ 'Here is the research data you already gathered:',
194
+ '',
195
+ toolContext.slice(0, 8000),
196
+ '',
197
+ NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT,
198
+ ].join('\n')
199
+
200
+ const followUp = yield* Effect.tryPromise({
201
+ try: () => params.synthesize(followUpPrompt, params.abortSignal),
202
+ catch: (error) => toDelegatedAgentError('follow-up-generate', params.label, error),
203
+ })
204
+
205
+ return yield* Effect.try({
206
+ try: () => assertSubstantiveAgentResult(followUp.text, params.label),
207
+ catch: (error) => toDelegatedAgentError('follow-up-validate', params.label, error),
208
+ }).pipe(
209
+ Effect.catch((secondError) =>
210
+ Effect.sync(() => {
211
+ aiLogger.error`Delegated agent follow-up also non-substantive (label=${params.label}, textLength=${followUp.text.length}, textPreview=${followUp.text.slice(0, 200)})`
212
+ }).pipe(Effect.andThen(Effect.fail(secondError))),
213
+ ),
214
+ )
215
+ }),
216
+ ),
217
+ )
218
+ })
180
219
  }
181
220
 
182
221
  export function createDelegatedAgentTool(definition: DelegatedAgentDefinition): ToolDefinition<void> {
@@ -189,32 +228,47 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
189
228
  tool({
190
229
  description: definition.description,
191
230
  inputSchema: z.object({ task: z.string().min(1) }),
192
- execute: async ({ task }: { task: string }, { abortSignal }) => {
193
- const agentTools = definition.tools
194
- const createAgent = () =>
195
- new ToolLoopAgent({
196
- id: definition.id,
197
- model: resolveAgentModel(definition.model),
198
- ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
199
- ...(definition.headers ? { headers: definition.headers } : {}),
200
- instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
201
- tools: agentTools,
202
- maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
203
- ...(typeof temperature === 'number' ? { temperature } : {}),
204
- stopWhen: [stepCountIs(maxSteps)],
205
- prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
206
- })
207
-
208
- return {
209
- task,
210
- result: await generateSubstantiveDelegatedAgentResult({
211
- label: `${definition.id} result`,
212
- task,
213
- abortSignal,
214
- createAgent,
231
+ execute: ({ task }: { task: string }, { abortSignal }) =>
232
+ Effect.runPromise(
233
+ Effect.gen(function* () {
234
+ const agentTools = definition.tools
235
+ const createAgent = () =>
236
+ new ToolLoopAgent({
237
+ id: definition.id,
238
+ model: resolveAgentModel(definition.model),
239
+ ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
240
+ ...(definition.headers ? { headers: definition.headers } : {}),
241
+ instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
242
+ tools: agentTools,
243
+ maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
244
+ ...(typeof temperature === 'number' ? { temperature } : {}),
245
+ stopWhen: [stepCountIs(maxSteps)],
246
+ prepareStep: ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
247
+ })
248
+ const synthesize = (prompt: string, abortSignal?: AbortSignal) =>
249
+ generateText({
250
+ model: resolveAgentModel(definition.model),
251
+ ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
252
+ ...(definition.headers ? { headers: definition.headers } : {}),
253
+ system: `${definition.instructions.trim()}\n\nReturn a complete final markdown answer using only the provided research data. Do not call tools.`,
254
+ prompt,
255
+ abortSignal,
256
+ maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
257
+ ...(typeof temperature === 'number' ? { temperature } : {}),
258
+ })
259
+
260
+ return {
261
+ task,
262
+ result: yield* generateSubstantiveDelegatedAgentResultEffect({
263
+ label: `${definition.id} result`,
264
+ task,
265
+ abortSignal,
266
+ createAgent,
267
+ synthesize,
268
+ }),
269
+ }
215
270
  }),
216
- }
217
- },
271
+ ),
218
272
  }),
219
273
  } as const satisfies ToolDefinition<void>
220
274
  }
@@ -231,32 +285,47 @@ export function createDelegatedAgentToolWithContext<TContext>(
231
285
  tool({
232
286
  description: definition.description,
233
287
  inputSchema: z.object({ task: z.string().min(1) }),
234
- execute: async ({ task }: { task: string }, { abortSignal }) => {
235
- const agentTools = definition.createTools(context)
236
- const createAgent = () =>
237
- new ToolLoopAgent({
238
- id: definition.id,
239
- model: resolveAgentModel(definition.model),
240
- ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
241
- ...(definition.headers ? { headers: definition.headers } : {}),
242
- instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
243
- tools: agentTools,
244
- maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
245
- ...(typeof temperature === 'number' ? { temperature } : {}),
246
- stopWhen: [stepCountIs(maxSteps)],
247
- prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
248
- })
249
-
250
- return {
251
- task,
252
- result: await generateSubstantiveDelegatedAgentResult({
253
- label: `${definition.id} result`,
254
- task,
255
- abortSignal,
256
- createAgent,
288
+ execute: ({ task }: { task: string }, { abortSignal }) =>
289
+ Effect.runPromise(
290
+ Effect.gen(function* () {
291
+ const agentTools = definition.createTools(context)
292
+ const createAgent = () =>
293
+ new ToolLoopAgent({
294
+ id: definition.id,
295
+ model: resolveAgentModel(definition.model),
296
+ ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
297
+ ...(definition.headers ? { headers: definition.headers } : {}),
298
+ instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
299
+ tools: agentTools,
300
+ maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
301
+ ...(typeof temperature === 'number' ? { temperature } : {}),
302
+ stopWhen: [stepCountIs(maxSteps)],
303
+ prepareStep: ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
304
+ })
305
+ const synthesize = (prompt: string, abortSignal?: AbortSignal) =>
306
+ generateText({
307
+ model: resolveAgentModel(definition.model),
308
+ ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
309
+ ...(definition.headers ? { headers: definition.headers } : {}),
310
+ system: `${definition.instructions.trim()}\n\nReturn a complete final markdown answer using only the provided research data. Do not call tools.`,
311
+ prompt,
312
+ abortSignal,
313
+ maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
314
+ ...(typeof temperature === 'number' ? { temperature } : {}),
315
+ })
316
+
317
+ return {
318
+ task,
319
+ result: yield* generateSubstantiveDelegatedAgentResultEffect({
320
+ label: `${definition.id} result`,
321
+ task,
322
+ abortSignal,
323
+ createAgent,
324
+ synthesize,
325
+ }),
326
+ }
257
327
  }),
258
- }
259
- },
328
+ ),
260
329
  }),
261
330
  } as const satisfies ToolDefinition<TContext>
262
331
  }
@@ -1,6 +1,6 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
 
3
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
3
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
4
4
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
5
5
  import {
6
6
  OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
@@ -32,7 +32,7 @@ Set every item.relevance as a string; use empty string when no reason is needed.
32
32
  export function createMemoryRerankerAgent(options: CreateHelperToolLoopAgentOptions) {
33
33
  return new ToolLoopAgent({
34
34
  id: 'memory-reranker',
35
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
35
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
36
36
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
37
37
  providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
38
38
  ...resolveHelperAgentOptions(options),
@@ -1,6 +1,6 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
 
3
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
3
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
4
4
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
5
5
  import {
6
6
  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -52,7 +52,7 @@ Return only the schema fields with no extra formatting.
52
52
  export function createOrgMemoryAgent(options: CreateHelperToolLoopAgentOptions) {
53
53
  return new ToolLoopAgent({
54
54
  id: 'org-memory',
55
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
55
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
56
56
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
57
57
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
58
58
  ...resolveHelperAgentOptions(options),
@@ -1,6 +1,6 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
 
3
- import { aiGatewayModel } from '../ai-gateway/ai-gateway'
3
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
4
4
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
5
5
  import { getLeadAgentDisplayName } from '../config/agent-defaults'
6
6
  import {
@@ -79,7 +79,7 @@ Return only the title text. No quotes, labels, JSON, markdown, or explanation.
79
79
  export function createRecentActivityTitleRefinerAgent(options: CreateHelperToolLoopAgentOptions) {
80
80
  return new ToolLoopAgent({
81
81
  id: 'recent-activity-title-refiner',
82
- model: aiGatewayModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
82
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
83
83
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
84
84
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
85
85
  ...resolveHelperAgentOptions(options, {
@@ -1,6 +1,6 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
 
3
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
3
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
4
4
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
5
5
  import {
6
6
  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -27,7 +27,7 @@ Synthesize an updated workspace profile summary and durable memory facts from co
27
27
  export function createRegularChatMemoryDigestAgent(options: CreateHelperToolLoopAgentOptions) {
28
28
  return new ToolLoopAgent({
29
29
  id: 'regular-chat-memory-digest',
30
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
30
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
31
31
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
32
32
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
33
33
  ...resolveHelperAgentOptions(options, {
@@ -1,7 +1,7 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
  import { z } from 'zod'
3
3
 
4
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
4
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
5
5
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
6
6
  import {
7
7
  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -45,7 +45,7 @@ export type SkillCandidate = z.infer<typeof SkillCandidateSchema>
45
45
  export function createSkillExtractorAgent(options: CreateHelperToolLoopAgentOptions) {
46
46
  return new ToolLoopAgent({
47
47
  id: 'skill-extractor',
48
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
48
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
49
49
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
50
50
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
51
51
  ...resolveHelperAgentOptions(options, {
@@ -1,7 +1,7 @@
1
1
  import { ToolLoopAgent } from 'ai'
2
2
  import { z } from 'zod'
3
3
 
4
- import { aiGatewayOpenRouterResponseHealingModel } from '../ai-gateway/ai-gateway'
4
+ import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
5
5
  import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
6
6
  import {
7
7
  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -69,7 +69,7 @@ export const SkillManagerOutputSchema = z.object({
69
69
  export function createSkillManagerAgent(options: CreateHelperToolLoopAgentOptions) {
70
70
  return new ToolLoopAgent({
71
71
  id: 'skill-manager',
72
- model: aiGatewayOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
72
+ model: aiGatewayChatModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
73
73
  headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
74
74
  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
75
75
  ...resolveHelperAgentOptions(options, {