maka-agent 0.2.0-dev.41.20260918 → 0.2.0-dev.43.20260919

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 (54) hide show
  1. package/LICENSE +7 -4
  2. package/dist/acp/maka-acp-agent.js +17 -6
  3. package/dist/acp/session-event-mapper.js +6 -0
  4. package/dist/acp/session-interactions.js +520 -0
  5. package/dist/acp/session-registry.js +80 -9
  6. package/dist/acp/tool-event-mapper.js +60 -2
  7. package/dist/pi-tui-runner.js +57 -6
  8. package/native/runtime-host-windows-task-launcher/prebuilds/win32-x64/maka-runtime-host-task-launcher.exe +0 -0
  9. package/node_modules/@maka/core/dist/client-plugin-bridge.js +19 -0
  10. package/node_modules/@maka/core/dist/connection-usage.js +27 -0
  11. package/node_modules/@maka/core/dist/events.js +58 -7
  12. package/node_modules/@maka/core/dist/external-session.js +4 -3
  13. package/node_modules/@maka/core/dist/interaction.js +38 -4
  14. package/node_modules/@maka/core/dist/llm-connections.js +4 -0
  15. package/node_modules/@maka/core/dist/model-metadata.js +89 -0
  16. package/node_modules/@maka/core/dist/provider-auth.js +9 -1
  17. package/node_modules/@maka/core/dist/recall.js +198 -15
  18. package/node_modules/@maka/core/dist/redaction.js +8 -0
  19. package/node_modules/@maka/core/dist/session-reference.js +149 -0
  20. package/node_modules/@maka/core/dist/skill-locations.js +29 -0
  21. package/node_modules/@maka/core/package.json +4 -0
  22. package/node_modules/@maka/runtime/dist/commandcode-cli-language-model.js +27 -3
  23. package/node_modules/@maka/runtime/dist/connection-usage.js +232 -0
  24. package/node_modules/@maka/runtime/dist/model-factory.js +5 -3
  25. package/node_modules/@maka/runtime/dist/model-history.js +13 -2
  26. package/node_modules/@maka/runtime/dist/plugin-client-bridge-service.js +308 -0
  27. package/node_modules/@maka/runtime/dist/plugin-composition-loader.js +4 -3
  28. package/node_modules/@maka/runtime/dist/plugin-data-services.js +3 -3
  29. package/node_modules/@maka/runtime/dist/recall-tools.js +70 -2
  30. package/node_modules/@maka/runtime/dist/skills-discovery.js +17 -23
  31. package/node_modules/@maka/runtime/package.json +2 -0
  32. package/node_modules/@maka/runtime-host/dist/protocol/connection-effects.js +132 -1
  33. package/node_modules/@maka/runtime-host/dist/protocol/index.js +11 -1
  34. package/node_modules/@maka/runtime-host/dist/protocol/operations.js +6 -0
  35. package/node_modules/@maka/runtime-host/dist/protocol/plugin-platform.js +269 -0
  36. package/node_modules/@maka/runtime-host/dist/protocol/workhub-coordination.js +2 -0
  37. package/node_modules/@maka/runtime-host/dist/server/connection-effect-coordinator.js +57 -1
  38. package/node_modules/@maka/runtime-host/dist/server/execution-composition.js +50 -9
  39. package/node_modules/@maka/runtime-host/dist/server/extension-package-manifest.js +19 -1
  40. package/node_modules/@maka/runtime-host/dist/server/plugin-package-loader.js +88 -14
  41. package/node_modules/@maka/runtime-host/dist/server/plugin-package-store.js +22 -5
  42. package/node_modules/@maka/runtime-host/dist/server/plugin-platform-coordinator.js +122 -1
  43. package/node_modules/@maka/runtime-host/dist/server/plugin-platform.js +120 -1
  44. package/node_modules/@maka/runtime-host/dist/server/recall-material-fetch.js +92 -0
  45. package/node_modules/@maka/runtime-host/dist/server/root-turn-coordinator.js +14 -1
  46. package/node_modules/@maka/runtime-host/dist/server/session-catalog-coordinator.js +17 -1
  47. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-action-gate.js +67 -3
  48. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-coordinator.js +9 -3
  49. package/node_modules/@maka/runtime-host/dist/server/workhub-target-execution-authority.js +161 -0
  50. package/node_modules/@maka/storage/dist/codex-session-adapter.js +26 -28
  51. package/node_modules/@maka/storage/dist/runtime-policy/coordinator.js +34 -1
  52. package/node_modules/@maka/storage/dist/runtime-policy-stores.js +2 -0
  53. package/node_modules/@maka/storage/dist/session-store.js +5 -2
  54. package/package.json +1 -1
@@ -77,8 +77,8 @@ const CLOSURE_OUTCOME_SHAPE = defineObjectShape()(['kind', 'reason', 'committedA
77
77
  const QUESTION_SHAPE = defineObjectShape()(['question', 'options'], []);
78
78
  const OPTION_SHAPE = defineObjectShape()(['label'], ['description']);
79
79
  const FORM_REQUESTER_SHAPE = defineObjectShape()(['name'], ['source']);
80
- const FORM_OPTION_SHAPE = defineObjectShape()(['value', 'label'], []);
81
- const FORM_STRING_FIELD_SHAPE = defineObjectShape()(['kind', 'name', 'label', 'required'], ['description', 'default', 'minLength', 'maxLength', 'format']);
80
+ const FORM_OPTION_SHAPE = defineObjectShape()(['value', 'label'], ['description']);
81
+ const FORM_STRING_FIELD_SHAPE = defineObjectShape()(['kind', 'name', 'label', 'required'], ['description', 'default', 'minLength', 'maxLength', 'format', 'presentation']);
82
82
  const FORM_NUMBER_FIELD_SHAPE = defineObjectShape()(['kind', 'name', 'label', 'required'], ['description', 'default', 'minimum', 'maximum']);
83
83
  const FORM_BOOLEAN_FIELD_SHAPE = defineObjectShape()(['kind', 'name', 'label', 'required'], ['description', 'default']);
84
84
  const FORM_SINGLE_SELECT_FIELD_SHAPE = defineObjectShape()(['kind', 'name', 'label', 'required', 'options'], ['description', 'default']);
@@ -405,6 +405,11 @@ function projectInteractionFormField(field) {
405
405
  const options = field.options.map((option) => ({
406
406
  ...option,
407
407
  label: projectInteractionReviewText(option.label, INTERACTION_FORM_FIELD_LABEL_MAX_BYTES),
408
+ ...(option.description === undefined
409
+ ? {}
410
+ : {
411
+ description: projectInteractionReviewText(option.description, INTERACTION_FORM_FIELD_DESCRIPTION_MAX_BYTES, true),
412
+ }),
408
413
  }));
409
414
  if (new Set(options.map((option) => option.label)).size !== options.length) {
410
415
  throw new Error('Form option labels collide after safe projection');
@@ -573,7 +578,15 @@ function decodeFormField(value) {
573
578
  : {
574
579
  format: oneOf(record.format, ['email', 'uri', 'date', 'date-time'], 'form string format'),
575
580
  }),
581
+ ...(record.presentation === undefined
582
+ ? {}
583
+ : {
584
+ presentation: oneOf(record.presentation, ['model_picker'], 'string presentation'),
585
+ }),
576
586
  };
587
+ if (field.presentation === 'model_picker' && field.format !== undefined) {
588
+ throw new Error('Model picker string field cannot declare a format');
589
+ }
577
590
  if (field.default !== undefined && !isInteractionFormFieldValueValid(field, field.default)) {
578
591
  throw new Error('Invalid form string default');
579
592
  }
@@ -674,6 +687,11 @@ function decodeFormOptions(value) {
674
687
  return Object.freeze({
675
688
  value: boundedText(record.value, 'form option value', INTERACTION_FORM_VALUE_MAX_BYTES),
676
689
  label: boundedString(record.label, 'form option label', INTERACTION_FORM_FIELD_LABEL_MAX_BYTES),
690
+ ...(record.description === undefined
691
+ ? {}
692
+ : {
693
+ description: boundedText(record.description, 'form option description', INTERACTION_FORM_FIELD_DESCRIPTION_MAX_BYTES),
694
+ }),
677
695
  });
678
696
  });
679
697
  if (new Set(options.map((option) => option.value)).size !== options.length) {
@@ -737,7 +755,8 @@ export function isInteractionFormFieldValueValid(field, value) {
737
755
  const length = [...value].length;
738
756
  return ((field.minLength === undefined || length >= field.minLength) &&
739
757
  (field.maxLength === undefined || length <= field.maxLength) &&
740
- matchesStringFormat(value, field.format));
758
+ matchesStringFormat(value, field.format) &&
759
+ (field.presentation !== 'model_picker' || isCanonicalModelChoiceValue(value)));
741
760
  }
742
761
  if (field.kind === 'number' || field.kind === 'integer') {
743
762
  return (typeof value === 'number' &&
@@ -836,8 +855,9 @@ function formFieldMaximumEnvelope(field) {
836
855
  if (field.format === 'date')
837
856
  return '0000-01-01';
838
857
  const maximumCodePoints = Math.min(field.maxLength ?? INTERACTION_FORM_VALUE_MAX_BYTES, INTERACTION_FORM_VALUE_MAX_BYTES);
839
- if (field.format === 'date-time')
858
+ if (field.format === 'date-time' || field.presentation === 'model_picker') {
840
859
  return '0'.repeat(maximumCodePoints);
860
+ }
841
861
  return '\u0001'.repeat(maximumCodePoints);
842
862
  }
843
863
  if (field.kind === 'number' || field.kind === 'integer')
@@ -852,6 +872,17 @@ function formFieldMaximumEnvelope(field) {
852
872
  .slice(0, field.maxItems ?? field.options.length)
853
873
  .map((option) => option.value);
854
874
  }
875
+ function isCanonicalModelChoiceValue(value) {
876
+ const components = value.split(':');
877
+ if (components.length !== 3 || components.some((component) => component.length === 0))
878
+ return false;
879
+ try {
880
+ return components.every((component) => encodeURIComponent(decodeURIComponent(component)) === component);
881
+ }
882
+ catch {
883
+ return false;
884
+ }
885
+ }
855
886
  function serializedByteLength(value) {
856
887
  return UTF8.encode(JSON.stringify(value)).byteLength;
857
888
  }
@@ -884,6 +915,9 @@ function formFieldWitness(field) {
884
915
  const fractionalLength = minLength <= 20 ? 0 : Math.max(1, minLength - 21);
885
916
  value = fractionalLength === 0 ? `${base}Z` : `${base}.${'0'.repeat(fractionalLength)}Z`;
886
917
  }
918
+ else if (field.presentation === 'model_picker') {
919
+ value = `a:a:${'a'.repeat(Math.max(1, minLength - 4))}`;
920
+ }
887
921
  else {
888
922
  value = 'a'.repeat(minLength);
889
923
  }
@@ -27,6 +27,10 @@ const MODEL_MODALITIES = ['text', 'image', 'audio', 'pdf', 'video'];
27
27
  export function isModelModality(value) {
28
28
  return MODEL_MODALITIES.includes(value);
29
29
  }
30
+ /** Stable client/Host value for one exact configured connection and model. */
31
+ export function connectionModelChoiceValue(connectionId, connectionSlug, model) {
32
+ return `${encodeURIComponent(connectionId)}:${encodeURIComponent(connectionSlug)}:${encodeURIComponent(model)}`;
33
+ }
30
34
  /**
31
35
  * Read-time normalizer: the model ids a stored connection exposes.
32
36
  *
@@ -318,6 +318,92 @@ function ollamaCloudThinkingModels(active) {
318
318
  !id.startsWith('gpt-oss'))
319
319
  .map(([id]) => [id, { thinkingOptions: OLLAMA_CLOUD_STANDARD_THINKING_OPTIONS }]));
320
320
  }
321
+ // Command Code declares no reasoning metadata over its API — the public
322
+ // `/provider/v1/models` listing carries only id/object/created/owned_by/name/
323
+ // context_length/supported_endpoints, and `/provider/v1/models/<id>` is not a
324
+ // route. The selectable `reasoning_effort` levels therefore live only in the
325
+ // official CLI's bundled model table, which the MIT `pi-commandcode-provider`
326
+ // project and its derivative `Mars-Sea/dsh-commandcode-provider`
327
+ // (`src/capabilities.ts`, `KNOWN_EFFORTS`) are the traceable extraction of.
328
+ //
329
+ // Ported from `dsh-commandcode-provider`'s `KNOWN_EFFORTS`, which was
330
+ // re-verified against `command-code@1.53.0` (`dist/cli.mjs`'s provider effort
331
+ // map). The reference keeps a running changelog of which CLI release added or
332
+ // removed each line; that history is summarized here per entry. We pin
333
+ // `command-code@1.54.0`, so a future re-sync should re-read that release's
334
+ // bundle — a wrong effort word is refused by the wire or ignored by the model,
335
+ // it is not silently mis-billed.
336
+ //
337
+ // Two rules from the reference that must survive re-syncs:
338
+ // - Models that reason automatically under a depth Command Code chooses
339
+ // (Tencent Hy3/Hy4 without levels, GLM-5/5.1/5.2-Fast, and the previews in
340
+ // the reference's `KNOWN_THINKING_MODELS`) carry no selectable effort, so
341
+ // they are absent here and the picker offers no selector for them.
342
+ // - Only the Provider-API table is authoritative for this route. Do not add
343
+ // levels observed on the OAuth (anthropic/openai) tables.
344
+ const COMMAND_CODE_MODEL_METADATA = {
345
+ 'Qwen/Qwen3.8-Max': { thinkingOptions: { efforts: ['low', 'medium', 'xhigh'] } },
346
+ 'Qwen/Qwen3.8-Max-0902': { thinkingOptions: { efforts: ['low', 'medium', 'xhigh'] } },
347
+ 'Qwen/Qwen3.8-27B': { thinkingOptions: { efforts: ['low', 'medium', 'xhigh'] } },
348
+ 'Qwen/Qwen3.8-Flash': { thinkingOptions: { efforts: ['low', 'medium', 'xhigh'] } },
349
+ 'claude-fable-5-1': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
350
+ 'claude-fable-5': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
351
+ 'claude-opus-4-7': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
352
+ 'claude-opus-4-8': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
353
+ 'claude-opus-5': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
354
+ 'claude-sonnet-4-6': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
355
+ 'claude-sonnet-5': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
356
+ // 1.39.0 added the model; 1.39.1 dropped `medium`; 1.39.2 ships this set.
357
+ 'deepseek/deepseek-v4-flash-fast': { thinkingOptions: { efforts: ['low', 'high', 'max'] } },
358
+ // 1.53.0 added DeepSeek V4.1 Flash with this set.
359
+ 'deepseek/deepseek-v4.1-flash': { thinkingOptions: { efforts: ['low', 'high', 'max'] } },
360
+ 'deepseek/deepseek-v4-flash': { thinkingOptions: { efforts: ['high', 'max'] } },
361
+ 'deepseek/deepseek-v4-flash-vision-exp': { thinkingOptions: { efforts: ['high', 'max'] } },
362
+ 'deepseek/deepseek-v4-pro': { thinkingOptions: { efforts: ['high', 'max'] } },
363
+ 'google/gemini-3.1-flash-lite': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
364
+ 'google/gemini-3.5-flash': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
365
+ 'google/gemini-3.5-flash-lite': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
366
+ 'google/gemini-3.6-flash': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
367
+ 'google/gemini-3.7-flash': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
368
+ // 1.43.0 added Gemini 3.8 Flash with the family's three-level set.
369
+ 'google/gemini-3.8-flash': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
370
+ 'gpt-5.3-codex': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
371
+ 'gpt-5.4': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
372
+ 'gpt-5.4-mini': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
373
+ 'gpt-5.5': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
374
+ 'gpt-5.6-luna': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
375
+ 'gpt-5.6-sol': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
376
+ 'gpt-5.6-terra': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
377
+ // 1.39.3 gained selectable levels (previously thought automatically).
378
+ 'moonshotai/Kimi-K3': { thinkingOptions: { efforts: ['low', 'high', 'max'] } },
379
+ 'sakana/fugu-ultra': { thinkingOptions: { efforts: ['high', 'xhigh'] } },
380
+ // 1.38.0 gained selectable levels (previously thought automatically).
381
+ 'tencent/hy4-preview': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
382
+ 'xai/grok-4.5': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
383
+ 'xai/grok-4.6': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
384
+ // Successor of `stealth/ox-alpha`, removed in 1.34.0 with the same set.
385
+ 'z-ai/glm-5.3-flash': { thinkingOptions: { efforts: ['low', 'high', 'max'] } },
386
+ 'zai-org/GLM-5.2': { thinkingOptions: { efforts: ['high', 'max'] } },
387
+ 'zai-org/GLM-5.3': { thinkingOptions: { efforts: ['low', 'high', 'max'] } },
388
+ // Muse Spark gained selectable levels in 1.45.0; 1.48.0 added `max` to 1.3
389
+ // only, so 1.3 and 1.3-contributor now differ.
390
+ 'meta/muse-spark-1.1': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
391
+ 'meta/muse-spark-1.2': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] } },
392
+ 'meta/muse-spark-1.2-contributor': {
393
+ thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] },
394
+ },
395
+ 'meta/muse-spark-1.3': {
396
+ thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] },
397
+ },
398
+ 'meta/muse-spark-1.3-contributor': {
399
+ thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh'] },
400
+ },
401
+ // 1.49.0 added GPT-6 Astra with the five-level set.
402
+ 'gpt-6-astra': { thinkingOptions: { efforts: ['low', 'medium', 'high', 'xhigh', 'max'] } },
403
+ // 1.51.3 gave MiniMax M3 selectable levels (read from the bundle; the
404
+ // 1.51.1–1.51.3 changelog had not been published at extraction time).
405
+ 'MiniMaxAI/MiniMax-M3': { thinkingOptions: { efforts: ['low', 'medium', 'high'] } },
406
+ };
321
407
  // Facts that models.dev cannot express: provider wire controls and
322
408
  // access-path-specific aliases/limits. Standard model facts stay generated.
323
409
  //
@@ -327,6 +413,9 @@ function buildStaticModelMetadata(active) {
327
413
  return {
328
414
  anthropic: ANTHROPIC_MODEL_OVERRIDES,
329
415
  'claude-subscription': claudeSubscriptionModelMetadata(active),
416
+ // Both Command Code providers ride the same Provider-API effort table.
417
+ commandcode: COMMAND_CODE_MODEL_METADATA,
418
+ 'commandcode-go': COMMAND_CODE_MODEL_METADATA,
330
419
  'alibaba-token-plan-cn': {
331
420
  'qwen3.8-max': {
332
421
  thinkingOptions: { efforts: ['none', 'low', 'medium', 'xhigh'], toggle: true },
@@ -22,7 +22,12 @@ import { providerAuthRequiresSecret, providerDefaultsOf, providerSupportsModelDi
22
22
  * storage coordinator actually gates — an operation with no admission point
23
23
  * does not belong here, however natural it sounds beside these three.
24
24
  */
25
- export const PROVIDER_AUTH_ACTIONS = ['test_credentials', 'fetch_models', 'start_oauth'];
25
+ export const PROVIDER_AUTH_ACTIONS = [
26
+ 'test_credentials',
27
+ 'fetch_models',
28
+ 'read_usage',
29
+ 'start_oauth',
30
+ ];
26
31
  /**
27
32
  * Which credential operations a connection may run. This is an admission
28
33
  * answer, not a UI state: the storage layer refuses an unavailable action, so a
@@ -67,6 +72,9 @@ export function deriveProviderAuthContract(input) {
67
72
  actionAvailability: actions({
68
73
  test_credentials: reachableWithoutSecret || hasSecret,
69
74
  fetch_models: canFetchModels && (reachableWithoutSecret || hasSecret),
75
+ // Reading account usage needs the same reachability as a connection test:
76
+ // a credential the provider accepts over HTTP.
77
+ read_usage: reachableWithoutSecret || hasSecret,
70
78
  }),
71
79
  };
72
80
  }
@@ -52,6 +52,9 @@
52
52
  * plus one weight that BM25 has no way to express: a tool result's term
53
53
  * density reflects machine output rather than relevance.
54
54
  */
55
+ import { isCanonicalArtifactEntityId } from './artifacts.js';
56
+ import { formatAttachmentResourceRef, MAX_ATTACHMENT_COUNT } from './attachments.js';
57
+ import { isAttachmentRef } from './events.js';
55
58
  import { validateWorkspacePrivacyContext } from './incognito.js';
56
59
  import { redactSecrets } from './redaction.js';
57
60
  import { SEARCH_QUERY_MAX_CHARS } from './search.js';
@@ -180,6 +183,76 @@ function stripSyntheticText(text, patterns) {
180
183
  stripped = stripped.replace(pattern, '');
181
184
  return stripped;
182
185
  }
186
+ /**
187
+ * The files a message carried. A screenshot pasted under "have a look" leaves
188
+ * no trace in the text, so without this the message is unreachable by any
189
+ * term the user would think to search.
190
+ */
191
+ export function recallMaterials(message) {
192
+ if (message.type !== 'user')
193
+ return [];
194
+ const attachments = message.attachments;
195
+ if (!Array.isArray(attachments) || attachments.length === 0)
196
+ return [];
197
+ // Shape first, then the cap: a record older or stranger than the current
198
+ // shape projects nothing, and a run of those ahead of a valid attachment
199
+ // must not spend the cap that valid one needed.
200
+ return attachments
201
+ .filter(isAttachmentRef)
202
+ .slice(0, MAX_ATTACHMENT_COUNT)
203
+ .map((attachment) => {
204
+ const resource = readableAttachmentResource(attachment);
205
+ const location = retrievableMaterialLocation(attachment);
206
+ return {
207
+ name: attachment.name,
208
+ kind: attachment.kind,
209
+ mimeType: attachment.mimeType,
210
+ bytes: attachment.bytes,
211
+ ...(resource ? { resource } : {}),
212
+ ...(location ?? {}),
213
+ };
214
+ });
215
+ }
216
+ /**
217
+ * The address `Read` accepts, present only for a material `Read` can actually
218
+ * return. `Read` answers an image with the image and anything else with the
219
+ * file's text, and refuses a PDF outright — so a PDF's address is one the
220
+ * caller can only fail on, which is the same reason a material in another
221
+ * Session carries no address.
222
+ */
223
+ function readableAttachmentResource(attachment) {
224
+ if (attachment.kind === 'pdf')
225
+ return null;
226
+ return formatAttachmentResourceRef(attachment.ref);
227
+ }
228
+ /**
229
+ * The pair that names a material a retrieval tool can fetch: the Session that
230
+ * holds it and the artifact inside it. Only a durable Session artifact can be
231
+ * fetched, so a ref of any other kind names nothing.
232
+ */
233
+ function retrievableMaterialLocation(attachment) {
234
+ if (attachment.ref.kind !== 'session_file')
235
+ return null;
236
+ if (!isCanonicalArtifactEntityId(attachment.ref.relativePath))
237
+ return null;
238
+ return {
239
+ sourceSessionId: attachment.ref.sessionId,
240
+ materialId: attachment.ref.relativePath,
241
+ };
242
+ }
243
+ /**
244
+ * What the predicate runs on: a message's prose plus the names of the files it
245
+ * carried, so a material is reachable by the name a person would remember.
246
+ * Names are matched but not returned as text — they come back as materials.
247
+ */
248
+ function recallMatchableText(message) {
249
+ const prose = recallSearchableText(message);
250
+ const materials = recallMaterials(message);
251
+ if (materials.length === 0)
252
+ return prose;
253
+ const names = materials.map((material) => material.name).join('\n');
254
+ return prose === undefined || prose.length === 0 ? names : `${prose}\n${names}`;
255
+ }
183
256
  /** Visits every string value in a JSON-like value, in document order, until the visitor declines. */
184
257
  function collectStringLeaves(value, visit) {
185
258
  if (typeof value === 'string')
@@ -261,7 +334,7 @@ export async function runRecall(request, deps, options = {}) {
261
334
  collected.hits.sort((left, right) => right.score - left.score || compareHitOrder(left, right));
262
335
  const sessionById = new Map(sessions.map((session) => [session.id, session]));
263
336
  const anchors = applySessionQuota(collected.hits, limit);
264
- const passages = assemblePassages(collected.transcripts, anchors, sessionById);
337
+ const passages = assemblePassages(collected.transcripts, anchors, sessionById, options.activeSessionId);
265
338
  return {
266
339
  ok: true,
267
340
  facts,
@@ -334,7 +407,7 @@ export async function expandRecallPassage(request, deps, options = {}) {
334
407
  if (!transcript) {
335
408
  return { ok: false, reason: 'not_found', message: 'That Session was not found.' };
336
409
  }
337
- const message = transcript.find((candidate) => candidate.id === anchorMessageId && recallSearchableText(candidate) !== undefined);
410
+ const message = transcript.find((candidate) => candidate.id === anchorMessageId && isPassageMessage(candidate));
338
411
  if (!message) {
339
412
  return { ok: false, reason: 'not_found', message: 'That passage anchor was not found.' };
340
413
  }
@@ -355,12 +428,77 @@ export async function expandRecallPassage(request, deps, options = {}) {
355
428
  tf: new Map(),
356
429
  matchedTerms: [],
357
430
  score: 0,
358
- }, transcript, session, RECALL_PASSAGE_MAX_BYTES, { before, after });
431
+ }, transcript, session, RECALL_PASSAGE_MAX_BYTES, options.activeSessionId, { before, after });
359
432
  if (!built) {
360
433
  return { ok: false, reason: 'not_found', message: 'That passage could not be rebuilt.' };
361
434
  }
362
435
  return { ok: true, passage: built.passage };
363
436
  }
437
+ /**
438
+ * Brings one material named by a passage into the asking Session.
439
+ *
440
+ * The Session check is the point of this function, not a formality: without it
441
+ * the tool would be a way to read any artifact by id, including from the
442
+ * Sessions recall itself refuses to surface — incognito, retired simulator
443
+ * transcripts, whatever a future rule excludes. A material is retrievable
444
+ * exactly when recall could have shown you the Session it sits in.
445
+ */
446
+ export async function fetchRecallMaterial(request, deps, options = {}) {
447
+ if (options.abortSignal?.aborted)
448
+ return aborted();
449
+ if (!deps.fetchMaterial) {
450
+ return { ok: false, reason: 'not_found', message: 'Materials are unavailable here.' };
451
+ }
452
+ if (typeof request !== 'object' || request === null || Array.isArray(request)) {
453
+ return { ok: false, reason: 'invalid_query', message: 'Material request must be an object.' };
454
+ }
455
+ const record = request;
456
+ const sessionId = optionalString(record.sessionId);
457
+ const materialId = optionalString(record.materialId);
458
+ if (!sessionId || !materialId) {
459
+ return {
460
+ ok: false,
461
+ reason: 'invalid_query',
462
+ message: 'A material is named by its Session and its material id.',
463
+ };
464
+ }
465
+ if (!options.activeSessionId) {
466
+ return { ok: false, reason: 'not_found', message: 'Materials need an active Session.' };
467
+ }
468
+ const privacyPayload = await deps.getPrivacyContext();
469
+ if (options.abortSignal?.aborted)
470
+ return aborted();
471
+ const privacy = validateWorkspacePrivacyContext(privacyPayload);
472
+ if (!privacy.ok || privacy.value.incognitoActive) {
473
+ return {
474
+ ok: false,
475
+ reason: 'incognito_active',
476
+ message: 'Recall is unavailable while incognito is active.',
477
+ };
478
+ }
479
+ const sessions = eligibleSessions(collapseSessionRevisions(await deps.listSessions(), options.activeSessionId), { sessionId, includeArchived: options.includeArchived === true });
480
+ if (options.abortSignal?.aborted)
481
+ return aborted();
482
+ if (!sessions.some((candidate) => candidate.id === sessionId)) {
483
+ return { ok: false, reason: 'not_found', message: 'That material was not found.' };
484
+ }
485
+ const fetched = await deps.fetchMaterial({
486
+ sourceSessionId: sessionId,
487
+ materialId,
488
+ targetSessionId: options.activeSessionId,
489
+ ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
490
+ });
491
+ if (options.abortSignal?.aborted)
492
+ return aborted();
493
+ if (!fetched.ok) {
494
+ return {
495
+ ok: false,
496
+ reason: fetched.reason === 'unsupported' ? 'invalid_query' : 'not_found',
497
+ message: fetched.message,
498
+ };
499
+ }
500
+ return { ok: true, content: fetched.content };
501
+ }
364
502
  function normalizeSpan(value) {
365
503
  if (value === undefined)
366
504
  return RECALL_EXPAND_MAX_NEIGHBOURS;
@@ -602,7 +740,7 @@ function verify(sessionId, message, input) {
602
740
  if (sessionId === input.activeSessionId && turnId && input.excludeTurnIds?.has(turnId)) {
603
741
  return undefined;
604
742
  }
605
- const raw = recallSearchableText(message);
743
+ const raw = recallMatchableText(message);
606
744
  if (raw === undefined)
607
745
  return undefined;
608
746
  // A hit is a term that occurs in the text as it was stored *and* still
@@ -738,7 +876,7 @@ function applySessionQuota(hits, limit) {
738
876
  // first when the total cap binds.
739
877
  return selected.sort((left, right) => right.score - left.score);
740
878
  }
741
- function assemblePassages(transcripts, anchors, sessionById) {
879
+ function assemblePassages(transcripts, anchors, sessionById, activeSessionId) {
742
880
  if (anchors.length === 0)
743
881
  return [];
744
882
  const passages = [];
@@ -749,7 +887,7 @@ function assemblePassages(transcripts, anchors, sessionById) {
749
887
  const transcript = transcripts.get(anchor.sessionId);
750
888
  if (!transcript)
751
889
  continue;
752
- const built = buildPassage(anchor, transcript, sessionById.get(anchor.sessionId), remaining);
890
+ const built = buildPassage(anchor, transcript, sessionById.get(anchor.sessionId), remaining, activeSessionId);
753
891
  if (!built)
754
892
  continue;
755
893
  remaining -= built.bytes;
@@ -757,7 +895,7 @@ function assemblePassages(transcripts, anchors, sessionById) {
757
895
  }
758
896
  return passages;
759
897
  }
760
- function buildPassage(anchor, transcript, session, budget, span = {
898
+ function buildPassage(anchor, transcript, session, budget, activeSessionId, span = {
761
899
  before: RECALL_PASSAGE_NEIGHBOURS,
762
900
  after: RECALL_PASSAGE_NEIGHBOURS,
763
901
  }) {
@@ -779,7 +917,7 @@ function buildPassage(anchor, transcript, session, budget, span = {
779
917
  const render = (message, isAnchor) => {
780
918
  if (rendered.has(message.id))
781
919
  return;
782
- const projected = projectPassageMessage(message, isAnchor);
920
+ const projected = projectPassageMessage(message, isAnchor, activeSessionId);
783
921
  if (!projected)
784
922
  return;
785
923
  const overhead = Buffer.byteLength(JSON.stringify({ ...projected, text: '' }), 'utf8');
@@ -816,8 +954,7 @@ function buildPassage(anchor, transcript, session, budget, span = {
816
954
  // the caller can still reach, so it counts toward the continuation flags the
817
955
  // same way one beyond the span does. Reporting otherwise would tell a caller
818
956
  // there is nothing more in a direction recall just cut short.
819
- const omitted = (entries) => entries.some((entry) => !rendered.has(entry.message.id) &&
820
- projectPassageMessage(entry.message, false) !== undefined);
957
+ const omitted = (entries) => entries.some((entry) => !rendered.has(entry.message.id) && isPassageMessage(entry.message));
821
958
  const passage = {
822
959
  sessionId: anchor.sessionId,
823
960
  sessionTitle: redactSecrets(session?.name ?? ''),
@@ -877,13 +1014,36 @@ function collectNeighbours(transcript, anchorIndex, turnId, span) {
877
1014
  function isPassageNeighbour(message) {
878
1015
  return message.type === 'user' || message.type === 'assistant' || message.type === 'tool_call';
879
1016
  }
880
- function projectPassageMessage(message, isAnchor) {
1017
+ /**
1018
+ * Whether a message can appear in a passage at all. Redaction rewrites text
1019
+ * but never empties it, so this decides the same set `projectPassageMessage`
1020
+ * does without paying for redaction on every message a lookup walks past.
1021
+ */
1022
+ function isPassageMessage(message) {
881
1023
  const raw = recallSearchableText(message);
882
- if (raw === undefined)
883
- return undefined;
884
- const text = redactSecrets(raw).trim();
885
- if (text.length === 0)
1024
+ if (raw !== undefined && raw.trim().length > 0)
1025
+ return true;
1026
+ return recallMaterials(message).length > 0;
1027
+ }
1028
+ function projectPassageMessage(message, isAnchor, activeSessionId) {
1029
+ const raw = recallSearchableText(message);
1030
+ const text = raw === undefined ? '' : redactSecrets(raw).trim();
1031
+ // A message whose whole content was a pasted file has no text of its own.
1032
+ // Dropping it would make the file unreachable in exactly the case this
1033
+ // layer exists for.
1034
+ // A file name is user-authored text like any other, so it leaves through the
1035
+ // same redaction the passage body does; the address beside it is a runtime
1036
+ // identifier and carries nothing to redact.
1037
+ const materials = recallMaterials(message).map((material) => ({
1038
+ ...material,
1039
+ name: redactSecrets(material.name),
1040
+ }));
1041
+ if (text.length === 0 && materials.length === 0)
886
1042
  return undefined;
1043
+ // A material carries an address or a location, never both: the address says
1044
+ // "read this now", the location says "ask for it and it will be brought
1045
+ // here". Offering an address `Read` would refuse is the mistake this split
1046
+ // exists to prevent.
887
1047
  return {
888
1048
  messageId: message.id,
889
1049
  role: passageRole(message),
@@ -891,6 +1051,29 @@ function projectPassageMessage(message, isAnchor) {
891
1051
  text,
892
1052
  timestamp: message.ts,
893
1053
  isAnchor,
1054
+ ...(materials.length > 0
1055
+ ? { materials: materials.map((material) => addressOrLocation(material, activeSessionId)) }
1056
+ : {}),
1057
+ };
1058
+ }
1059
+ /**
1060
+ * Reachability is a fact about where the material itself is stored, not about
1061
+ * the passage that mentioned it. Keying it on the passage would offer an
1062
+ * address for a ref pointing into another Session — the doomed address this
1063
+ * split exists to prevent, with the polarity inverted.
1064
+ */
1065
+ function addressOrLocation(material, activeSessionId) {
1066
+ const { resource, sourceSessionId, materialId, ...named } = material;
1067
+ if (resource && sourceSessionId !== undefined && sourceSessionId === activeSessionId) {
1068
+ return { ...named, resource };
1069
+ }
1070
+ // A location is a thing to ask for, so it is only worth carrying when
1071
+ // asking could succeed. A PDF is refused wherever it is stored.
1072
+ return {
1073
+ ...named,
1074
+ ...(sourceSessionId && materialId && named.kind !== 'pdf'
1075
+ ? { sourceSessionId, materialId }
1076
+ : {}),
894
1077
  };
895
1078
  }
896
1079
  function passageRole(message) {
@@ -197,6 +197,14 @@ export function classifyGeneralizedError(error) {
197
197
  return 'timeout';
198
198
  if (lower.includes('429') || lower.includes('rate'))
199
199
  return 'rate_limited';
200
+ // builder-util-runtime appends generic authentication-token advice to HTTP
201
+ // 404 errors. electron-updater has already classified this particular case
202
+ // as a missing channel artifact, so it is not evidence of bad credentials.
203
+ if (typeof error === 'object' &&
204
+ error !== null &&
205
+ 'code' in error &&
206
+ error.code === 'ERR_UPDATER_CHANNEL_FILE_NOT_FOUND')
207
+ return undefined;
200
208
  if (lower.includes('401') || lower.includes('403') || isAuthenticationErrorText(lower))
201
209
  return 'auth_failed';
202
210
  if (/\b5\d\d\b/.test(lower))