@lota-sdk/core 0.4.7 → 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/model-constants.ts +1 -0
  9. package/src/config/thread-defaults.ts +33 -21
  10. package/src/create-runtime.ts +725 -383
  11. package/src/db/base.service.ts +52 -28
  12. package/src/db/cursor-pagination.ts +71 -30
  13. package/src/db/memory-store.helpers.ts +4 -7
  14. package/src/db/memory-store.ts +856 -598
  15. package/src/db/memory.ts +398 -275
  16. package/src/db/record-id.ts +32 -10
  17. package/src/db/schema-fingerprint.ts +30 -12
  18. package/src/db/service-normalization.ts +255 -0
  19. package/src/db/service.ts +726 -761
  20. package/src/db/startup.ts +140 -66
  21. package/src/db/transaction-conflict.ts +15 -0
  22. package/src/effect/awaitable-effect.ts +87 -0
  23. package/src/effect/errors.ts +121 -0
  24. package/src/effect/helpers.ts +98 -0
  25. package/src/effect/index.ts +22 -0
  26. package/src/effect/layers.ts +228 -0
  27. package/src/effect/runtime-ref.ts +25 -0
  28. package/src/effect/runtime.ts +31 -0
  29. package/src/effect/services.ts +57 -0
  30. package/src/effect/zod.ts +43 -0
  31. package/src/embeddings/provider.ts +122 -71
  32. package/src/index.ts +46 -1
  33. package/src/openrouter/direct-provider.ts +29 -0
  34. package/src/queues/autonomous-job.queue.ts +130 -74
  35. package/src/queues/context-compaction.queue.ts +60 -15
  36. package/src/queues/delayed-node-promotion.queue.ts +52 -15
  37. package/src/queues/document-processor.queue.ts +52 -77
  38. package/src/queues/memory-consolidation.queue.ts +47 -32
  39. package/src/queues/organization-learning.queue.ts +13 -4
  40. package/src/queues/plan-agent-heartbeat.queue.ts +65 -21
  41. package/src/queues/plan-scheduler.queue.ts +107 -31
  42. package/src/queues/post-chat-memory.queue.ts +66 -24
  43. package/src/queues/queue-factory.ts +142 -52
  44. package/src/queues/standalone-worker.ts +39 -0
  45. package/src/queues/title-generation.queue.ts +54 -9
  46. package/src/redis/connection.ts +84 -32
  47. package/src/redis/index.ts +6 -8
  48. package/src/redis/org-memory-lock.ts +60 -27
  49. package/src/redis/redis-lease-lock.ts +200 -121
  50. package/src/redis/runtime-connection.ts +10 -0
  51. package/src/redis/stream-context.ts +84 -46
  52. package/src/runtime/agent-identity-overrides.ts +2 -2
  53. package/src/runtime/agent-runtime-policy.ts +4 -1
  54. package/src/runtime/agent-stream-helpers.ts +20 -9
  55. package/src/runtime/chat-run-orchestration.ts +102 -19
  56. package/src/runtime/chat-run-registry.ts +36 -2
  57. package/src/runtime/context-compaction/context-compaction-runtime.ts +107 -0
  58. package/src/runtime/{context-compaction.ts → context-compaction/context-compaction.ts} +114 -91
  59. package/src/runtime/execution-plan-visibility.ts +2 -2
  60. package/src/runtime/execution-plan.ts +42 -15
  61. package/src/runtime/graph-designer.ts +11 -7
  62. package/src/runtime/helper-model.ts +135 -48
  63. package/src/runtime/index.ts +7 -7
  64. package/src/runtime/indexed-repositories-policy.ts +3 -3
  65. package/src/runtime/{memory-block.ts → memory/memory-block.ts} +40 -36
  66. package/src/runtime/{memory-digest-policy.ts → memory/memory-digest-policy.ts} +1 -1
  67. package/src/runtime/{memory-pipeline.ts → memory/memory-pipeline.ts} +1 -1
  68. package/src/runtime/{memory-prompts-fact.ts → memory/memory-prompts-fact.ts} +2 -2
  69. package/src/runtime/{memory-scope.ts → memory/memory-scope.ts} +12 -6
  70. package/src/runtime/plugin-resolution.ts +144 -24
  71. package/src/runtime/plugin-types.ts +9 -1
  72. package/src/runtime/post-turn-side-effects.ts +197 -130
  73. package/src/runtime/retrieval-adapters.ts +38 -4
  74. package/src/runtime/runtime-config.ts +165 -61
  75. package/src/runtime/runtime-extensions.ts +21 -34
  76. package/src/runtime/social-chat/social-chat-agent-runner.ts +157 -0
  77. package/src/runtime/{social-chat-history.ts → social-chat/social-chat-history.ts} +42 -20
  78. package/src/runtime/social-chat/social-chat.ts +594 -0
  79. package/src/runtime/specialist-runner.ts +36 -10
  80. package/src/runtime/team-consultation/team-consultation-orchestrator.ts +427 -0
  81. package/src/runtime/{team-consultation-prompts.ts → team-consultation/team-consultation-prompts.ts} +6 -2
  82. package/src/runtime/thread-chat-helpers.ts +2 -2
  83. package/src/runtime/thread-plan-turn.ts +2 -1
  84. package/src/runtime/thread-turn-context.ts +172 -94
  85. package/src/runtime/turn-lifecycle.ts +93 -27
  86. package/src/services/agent-activity.service.ts +287 -203
  87. package/src/services/agent-executor.service.ts +329 -217
  88. package/src/services/artifact.service.ts +225 -148
  89. package/src/services/attachment.service.ts +137 -115
  90. package/src/services/autonomous-job.service.ts +888 -491
  91. package/src/services/chat-run-registry.service.ts +11 -1
  92. package/src/services/context-compaction.service.ts +136 -86
  93. package/src/services/document-chunk.service.ts +162 -90
  94. package/src/services/execution-plan/execution-plan-approval.ts +26 -0
  95. package/src/services/execution-plan/execution-plan-context.ts +29 -0
  96. package/src/services/execution-plan/execution-plan-graph.ts +256 -0
  97. package/src/services/execution-plan/execution-plan-schedule.ts +84 -0
  98. package/src/services/execution-plan/execution-plan-spec.ts +75 -0
  99. package/src/services/execution-plan/execution-plan.service.ts +1041 -0
  100. package/src/services/feedback-loop.service.ts +132 -76
  101. package/src/services/global-orchestrator.service.ts +80 -170
  102. package/src/services/graph-full-routing.ts +182 -0
  103. package/src/services/index.ts +18 -20
  104. package/src/services/institutional-memory.service.ts +220 -123
  105. package/src/services/learned-skill.service.ts +364 -259
  106. package/src/services/memory/memory-conversation.ts +95 -0
  107. package/src/services/memory/memory-org-memory.ts +39 -0
  108. package/src/services/memory/memory-preseeded.ts +80 -0
  109. package/src/services/memory/memory-rerank.ts +297 -0
  110. package/src/services/{memory-utils.ts → memory/memory-utils.ts} +5 -5
  111. package/src/services/memory/memory.service.ts +692 -0
  112. package/src/services/memory/rerank.service.ts +209 -0
  113. package/src/services/monitoring-window.service.ts +92 -70
  114. package/src/services/mutating-approval.service.ts +62 -53
  115. package/src/services/node-workspace.service.ts +141 -98
  116. package/src/services/notification.service.ts +17 -16
  117. package/src/services/organization-member.service.ts +120 -66
  118. package/src/services/organization.service.ts +144 -51
  119. package/src/services/ownership-dispatcher.service.ts +415 -264
  120. package/src/services/plan/plan-agent-heartbeat.service.ts +234 -0
  121. package/src/services/plan/plan-agent-query.service.ts +322 -0
  122. package/src/services/plan/plan-approval.service.ts +102 -0
  123. package/src/services/plan/plan-artifact.service.ts +60 -0
  124. package/src/services/plan/plan-builder.service.ts +76 -0
  125. package/src/services/plan/plan-checkpoint.service.ts +103 -0
  126. package/src/services/{plan-compiler.service.ts → plan/plan-compiler.service.ts} +26 -9
  127. package/src/services/plan/plan-completion-side-effects.ts +175 -0
  128. package/src/services/plan/plan-coordination.service.ts +181 -0
  129. package/src/services/plan/plan-cycle.service.ts +398 -0
  130. package/src/services/plan/plan-deadline.service.ts +547 -0
  131. package/src/services/plan/plan-event-delivery.service.ts +261 -0
  132. package/src/services/plan/plan-executor-context.ts +35 -0
  133. package/src/services/plan/plan-executor-graph.ts +475 -0
  134. package/src/services/plan/plan-executor-helpers.ts +322 -0
  135. package/src/services/plan/plan-executor-persistence.ts +209 -0
  136. package/src/services/plan/plan-executor.service.ts +1654 -0
  137. package/src/services/{plan-helpers.ts → plan/plan-helpers.ts} +1 -1
  138. package/src/services/{plan-run-data.ts → plan/plan-run-data.ts} +4 -4
  139. package/src/services/plan/plan-run-serialization.ts +15 -0
  140. package/src/services/plan/plan-run.service.ts +644 -0
  141. package/src/services/plan/plan-scheduler.service.ts +385 -0
  142. package/src/services/plan/plan-template.service.ts +224 -0
  143. package/src/services/plan/plan-transaction-events.ts +33 -0
  144. package/src/services/plan/plan-validator.service.ts +907 -0
  145. package/src/services/plan/plan-workspace.service.ts +125 -0
  146. package/src/services/plugin-executor.service.ts +97 -68
  147. package/src/services/quality-metrics.service.ts +112 -94
  148. package/src/services/queue-job.service.ts +296 -230
  149. package/src/services/recent-activity-title.service.ts +65 -36
  150. package/src/services/recent-activity.service.ts +274 -259
  151. package/src/services/skill-resolver.service.ts +38 -12
  152. package/src/services/social-chat-history.service.ts +176 -125
  153. package/src/services/system-executor.service.ts +91 -61
  154. package/src/services/thread/thread-active-run.ts +203 -0
  155. package/src/services/thread/thread-bootstrap.ts +369 -0
  156. package/src/services/thread/thread-listing.ts +198 -0
  157. package/src/services/thread/thread-memory-block.ts +117 -0
  158. package/src/services/thread/thread-message.service.ts +363 -0
  159. package/src/services/thread/thread-record-store.ts +155 -0
  160. package/src/services/thread/thread-title.service.ts +74 -0
  161. package/src/services/thread/thread-turn-execution.ts +280 -0
  162. package/src/services/thread/thread-turn-message-context.ts +73 -0
  163. package/src/services/thread/thread-turn-preparation.service.ts +1146 -0
  164. package/src/services/thread/thread-turn-streaming.ts +402 -0
  165. package/src/services/thread/thread-turn-tracing.ts +35 -0
  166. package/src/services/thread/thread-turn.ts +343 -0
  167. package/src/services/thread/thread.service.ts +335 -0
  168. package/src/services/user.service.ts +82 -32
  169. package/src/services/write-intent-validator.service.ts +63 -51
  170. package/src/storage/attachment-parser.ts +69 -27
  171. package/src/storage/attachment-storage.service.ts +331 -275
  172. package/src/storage/generated-document-storage.service.ts +66 -34
  173. package/src/system-agents/agent-result.ts +3 -1
  174. package/src/system-agents/context-compaction.agent.ts +2 -2
  175. package/src/system-agents/delegated-agent-factory.ts +159 -90
  176. package/src/system-agents/memory-reranker.agent.ts +2 -2
  177. package/src/system-agents/memory.agent.ts +2 -2
  178. package/src/system-agents/recent-activity-title-refiner.agent.ts +2 -2
  179. package/src/system-agents/regular-chat-memory-digest.agent.ts +2 -2
  180. package/src/system-agents/skill-extractor.agent.ts +2 -2
  181. package/src/system-agents/skill-manager.agent.ts +2 -2
  182. package/src/system-agents/thread-router.agent.ts +157 -113
  183. package/src/system-agents/title-generator.agent.ts +2 -2
  184. package/src/tools/execution-plan.tool.ts +220 -161
  185. package/src/tools/fetch-webpage.tool.ts +21 -17
  186. package/src/tools/firecrawl-client.ts +16 -6
  187. package/src/tools/index.ts +1 -0
  188. package/src/tools/memory-block.tool.ts +14 -6
  189. package/src/tools/plan-approval.tool.ts +49 -47
  190. package/src/tools/read-file-parts.tool.ts +44 -33
  191. package/src/tools/remember-memory.tool.ts +65 -45
  192. package/src/tools/search-web.tool.ts +26 -22
  193. package/src/tools/search.tool.ts +41 -29
  194. package/src/tools/team-think.tool.ts +124 -83
  195. package/src/tools/user-questions.tool.ts +4 -3
  196. package/src/tools/web-tool-shared.ts +6 -0
  197. package/src/utils/async.ts +17 -23
  198. package/src/utils/crypto.ts +21 -0
  199. package/src/utils/date-time.ts +40 -1
  200. package/src/utils/errors.ts +95 -16
  201. package/src/utils/hono-error-handler.ts +24 -39
  202. package/src/utils/index.ts +2 -1
  203. package/src/utils/null-proto-record.ts +41 -0
  204. package/src/utils/sse-keepalive.ts +124 -21
  205. package/src/workers/bootstrap.ts +186 -51
  206. package/src/workers/memory-consolidation.worker.ts +325 -237
  207. package/src/workers/organization-learning.worker.ts +50 -16
  208. package/src/workers/regular-chat-memory-digest.helpers.ts +28 -27
  209. package/src/workers/regular-chat-memory-digest.runner.ts +175 -114
  210. package/src/workers/skill-extraction.runner.ts +176 -93
  211. package/src/workers/utils/file-section-chunker.ts +8 -10
  212. package/src/workers/utils/repo-structure-extractor.ts +349 -260
  213. package/src/workers/utils/repomix-file-sections.ts +2 -2
  214. package/src/workers/utils/thread-message-query.ts +97 -38
  215. package/src/workers/worker-utils.ts +56 -31
  216. package/src/config/debug-logger.ts +0 -47
  217. package/src/redis/connection-accessor.ts +0 -26
  218. package/src/runtime/context-compaction-runtime.ts +0 -87
  219. package/src/runtime/social-chat-agent-runner.ts +0 -118
  220. package/src/runtime/social-chat.ts +0 -516
  221. package/src/runtime/team-consultation-orchestrator.ts +0 -272
  222. package/src/services/adaptive-playbook.service.ts +0 -152
  223. package/src/services/artifact-provenance.service.ts +0 -172
  224. package/src/services/chat-attachments.service.ts +0 -17
  225. package/src/services/context-compaction-runtime.singleton.ts +0 -13
  226. package/src/services/execution-plan.service.ts +0 -1118
  227. package/src/services/memory.service.ts +0 -844
  228. package/src/services/plan-agent-heartbeat.service.ts +0 -136
  229. package/src/services/plan-agent-query.service.ts +0 -267
  230. package/src/services/plan-approval.service.ts +0 -83
  231. package/src/services/plan-artifact.service.ts +0 -50
  232. package/src/services/plan-builder.service.ts +0 -67
  233. package/src/services/plan-checkpoint.service.ts +0 -81
  234. package/src/services/plan-completion-side-effects.ts +0 -80
  235. package/src/services/plan-coordination.service.ts +0 -157
  236. package/src/services/plan-cycle.service.ts +0 -284
  237. package/src/services/plan-deadline.service.ts +0 -430
  238. package/src/services/plan-event-delivery.service.ts +0 -166
  239. package/src/services/plan-executor.service.ts +0 -1950
  240. package/src/services/plan-run.service.ts +0 -515
  241. package/src/services/plan-scheduler.service.ts +0 -240
  242. package/src/services/plan-template.service.ts +0 -177
  243. package/src/services/plan-validator.service.ts +0 -818
  244. package/src/services/plan-workspace.service.ts +0 -83
  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, {