@openllmsh/sdk 2.10.15-alpha.7 → 2.10.15-alpha.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.
@@ -59,11 +59,16 @@ export declare const AGENT_HOOK_LOCAL_PATH = "/local/agent-hook";
59
59
  * engine's readiness signal: Claude runs it once the TUI is up (after any
60
60
  * folder-trust dialog), so a queued web prompt is pasted only then.
61
61
  */
62
- export declare const AGENT_HOOK_EVENTS: readonly ["PermissionRequest", "PreToolUse", "Stop", "SessionStart"];
62
+ export declare const AGENT_HOOK_EVENTS: readonly ["PermissionRequest", "PreToolUse", "Stop", "SessionStart", "UserPromptSubmit"];
63
63
  /** Max inline attachments on one `send`. */
64
64
  export declare const AGENT_MAX_ATTACHMENTS = 8;
65
- /** Max base64 characters of one inline attachment. */
65
+ /** Max base64 characters of one `attachment.data` chunk. */
66
66
  export declare const AGENT_MAX_ATTACHMENT_BASE64_LENGTH: number;
67
+ /**
68
+ * Decoded bytes of one `attachment_put` chunk. Small enough that a chunk
69
+ * never crowds the stream; each one is acknowledged before the next.
70
+ */
71
+ export declare const AGENT_ATTACHMENT_PUT_CHUNK_BYTES: number;
67
72
  /**
68
73
  * Max characters of one absolute local-path attachment (same bound as a
69
74
  * session cwd). Path attachments are loopback-only and never cross the network.
@@ -105,26 +110,30 @@ export declare const AgentStreamOpenPayload: S.Struct<{
105
110
  readonly kind: S.Literal<"agent">;
106
111
  }>;
107
112
  export type TAgentStreamOpenPayload = S.Schema.Type<typeof AgentStreamOpenPayload>;
113
+ /** A cached attachment's id: the lowercase hex SHA-256 of its bytes. */
114
+ export declare const AGENT_ATTACHMENT_SHA256_PATTERN: RegExp;
115
+ export declare const AgentAttachmentSha256: S.String;
108
116
  /**
109
- * One attachment on `send`. Exactly one of `data` (base64, any transport) or
110
- * `path` (absolute local file, loopback agent socket only — the daemon rejects
111
- * `path` on mux/RTC). Both together are refused (same XOR pattern as
112
- * {@link AgentRespondCommand}).
117
+ * One attachment on `send`. Exactly one of `sha256` (bytes the consumer put
118
+ * into the device's attachment cache with {@link AgentAttachmentPutCommand},
119
+ * any transport) or `path` (an absolute file on the device, sent as a plain
120
+ * path in the prompt on any transport; only the loopback socket reads its
121
+ * bytes back). Both together are refused.
113
122
  */
114
123
  export declare const AgentAttachment: S.Struct<{
115
124
  readonly kind: S.Literals<readonly ["image", "file"]>;
116
125
  readonly name: S.optional<S.String>;
117
126
  readonly media_type: S.String;
118
- /** Base64 bytes. Mutually exclusive with {@link path}. */
119
- readonly data: S.optional<S.String>;
120
- /** Absolute local path; admitted only on the desktop loopback agent socket. */
127
+ /** A cached upload. Mutually exclusive with {@link path}. */
128
+ readonly sha256: S.optional<S.String>;
129
+ /** Absolute path on the device, admitted on any transport. */
121
130
  readonly path: S.optional<S.String>;
122
131
  }>;
123
132
  export type TAgentAttachment = S.Schema.Type<typeof AgentAttachment>;
124
- /** True when the attachment carries an absolute local path instead of bytes. */
133
+ /** True when the attachment names a file on the device instead of a cached upload. */
125
134
  export declare const agentAttachmentHasPath: (attachment: TAgentAttachment) => attachment is TAgentAttachment & {
126
135
  readonly path: string;
127
- readonly data?: undefined;
136
+ readonly sha256?: undefined;
128
137
  };
129
138
  /**
130
139
  * Whether a path string can ride Claude's quoted `@"…"` mention: non-empty,
@@ -146,15 +155,13 @@ export declare const AgentAttachmentMeta: S.Struct<{
146
155
  readonly size: S.Number;
147
156
  }>;
148
157
  export type TAgentAttachmentMeta = S.Schema.Type<typeof AgentAttachmentMeta>;
149
- /** Decoded-byte cap mirroring {@link AGENT_MAX_ATTACHMENT_BASE64_LENGTH}. */
150
- export declare const AGENT_MAX_ATTACHMENT_BYTES: number;
151
158
  /**
152
- * Cap for a `path` attachment on this Mac (loopback only). The send carries
153
- * no bytes, so {@link AGENT_MAX_ATTACHMENT_BYTES} doesn't apply; this bounds
154
- * the daemon's read when the transcript previews it (`attachment_get`,
155
- * chunked), so anything that can be sent can also be shown.
159
+ * Max bytes of one attachment, a cached upload or a path on the device alike.
160
+ * Uploads travel in {@link AGENT_ATTACHMENT_PUT_CHUNK_BYTES} chunks and
161
+ * previews come back chunked (`attachment_get`), so no single message carries
162
+ * a whole file.
156
163
  */
157
- export declare const AGENT_MAX_LOCAL_ATTACHMENT_BYTES: number;
164
+ export declare const AGENT_MAX_ATTACHMENT_BYTES: number;
158
165
  /** Decision on an approval request (`request.opened`). */
159
166
  export declare const AgentRequestDecision: S.Literals<readonly ["accept", "accept_for_session", "decline", "cancel"]>;
160
167
  export type TAgentRequestDecision = S.Schema.Type<typeof AgentRequestDecision>;
@@ -207,9 +214,9 @@ export declare const AgentSendCommand: S.Struct<{
207
214
  readonly kind: S.Literals<readonly ["image", "file"]>;
208
215
  readonly name: S.optional<S.String>;
209
216
  readonly media_type: S.String;
210
- /** Base64 bytes. Mutually exclusive with {@link path}. */
211
- readonly data: S.optional<S.String>;
212
- /** Absolute local path; admitted only on the desktop loopback agent socket. */
217
+ /** A cached upload. Mutually exclusive with {@link path}. */
218
+ readonly sha256: S.optional<S.String>;
219
+ /** Absolute path on the device, admitted on any transport. */
213
220
  readonly path: S.optional<S.String>;
214
221
  }>>>;
215
222
  }>;
@@ -279,6 +286,29 @@ export declare const AgentAttachmentGetCommand: S.Struct<{
279
286
  readonly name: S.String;
280
287
  }>;
281
288
  export type TAgentAttachmentGetCommand = S.Schema.Type<typeof AgentAttachmentGetCommand>;
289
+ /**
290
+ * Put one chunk of an attachment into the device's attachment cache, keyed by
291
+ * the SHA-256 of the whole file. Chunks go in order from offset 0, each
292
+ * acknowledged by an {@link AgentAttachmentStatusEvent} before the next; the
293
+ * file is stored once `done` and its hash and size check out. A first chunk
294
+ * with empty `data` asks whether the file is already cached (the reply says
295
+ * `stored`), so a file is never sent twice. Any transport: these are the
296
+ * consumer's own bytes, never a file the device already had.
297
+ */
298
+ export declare const AgentAttachmentPutCommand: S.Struct<{
299
+ readonly type: S.Literal<"attachment_put">;
300
+ readonly id: S.optional<S.String>;
301
+ readonly sha256: S.String;
302
+ /** Total bytes of the file. */
303
+ readonly size: S.Number;
304
+ /** Decoded-byte offset of this chunk. */
305
+ readonly offset: S.Number;
306
+ /** Base64 of this chunk (at most {@link AGENT_ATTACHMENT_PUT_CHUNK_BYTES}). */
307
+ readonly data: S.String;
308
+ /** This chunk ends the file. */
309
+ readonly done: S.Boolean;
310
+ }>;
311
+ export type TAgentAttachmentPutCommand = S.Schema.Type<typeof AgentAttachmentPutCommand>;
282
312
  /**
283
313
  * A model id a running session can switch to: gateway ids and Claude aliases
284
314
  * (`ultra`, `sonnet`, `openai/gpt-5`, `claude-opus-4-5[1m]`). No whitespace or
@@ -369,11 +399,23 @@ export declare const AgentCommand: S.Union<readonly [S.Struct<{
369
399
  readonly kind: S.Literals<readonly ["image", "file"]>;
370
400
  readonly name: S.optional<S.String>;
371
401
  readonly media_type: S.String;
372
- /** Base64 bytes. Mutually exclusive with {@link path}. */
373
- readonly data: S.optional<S.String>;
374
- /** Absolute local path; admitted only on the desktop loopback agent socket. */
402
+ /** A cached upload. Mutually exclusive with {@link path}. */
403
+ readonly sha256: S.optional<S.String>;
404
+ /** Absolute path on the device, admitted on any transport. */
375
405
  readonly path: S.optional<S.String>;
376
406
  }>>>;
407
+ }>, S.Struct<{
408
+ readonly type: S.Literal<"attachment_put">;
409
+ readonly id: S.optional<S.String>;
410
+ readonly sha256: S.String;
411
+ /** Total bytes of the file. */
412
+ readonly size: S.Number;
413
+ /** Decoded-byte offset of this chunk. */
414
+ readonly offset: S.Number;
415
+ /** Base64 of this chunk (at most {@link AGENT_ATTACHMENT_PUT_CHUNK_BYTES}). */
416
+ readonly data: S.String;
417
+ /** This chunk ends the file. */
418
+ readonly done: S.Boolean;
377
419
  }>, S.Struct<{
378
420
  readonly type: S.Literal<"send_now">;
379
421
  readonly id: S.optional<S.String>;
@@ -989,6 +1031,26 @@ export declare const AgentAttachmentDataEvent: S.Struct<{
989
1031
  readonly done: S.Boolean;
990
1032
  }>;
991
1033
  export type TAgentAttachmentDataEvent = S.Schema.Type<typeof AgentAttachmentDataEvent>;
1034
+ /**
1035
+ * Answer to every `attachment_put` (same `command_id`): `stored` once the
1036
+ * file is in the cache (at once for a file already there), otherwise how many
1037
+ * bytes the device holds so far, so the consumer sends the next chunk.
1038
+ */
1039
+ export declare const AgentAttachmentStatusEvent: S.Struct<{
1040
+ /** The session this event belongs to (absent only before one exists). */
1041
+ readonly session_id: S.optional<S.String>;
1042
+ /** Daemon-assigned ordinal, monotonically increasing per session. */
1043
+ readonly seq: S.optional<S.Number>;
1044
+ /** Epoch milliseconds on the daemon. */
1045
+ readonly at: S.optional<S.Number>;
1046
+ /** Echo of the {@link AgentCommand} `id` this event answers, if any. */
1047
+ readonly command_id: S.optional<S.String>;
1048
+ readonly type: S.Literal<"attachment.status">;
1049
+ readonly sha256: S.String;
1050
+ readonly stored: S.Boolean;
1051
+ readonly received: S.Number;
1052
+ }>;
1053
+ export type TAgentAttachmentStatusEvent = S.Schema.Type<typeof AgentAttachmentStatusEvent>;
992
1054
  /** Answer to `delete_session`: the session is gone from the device. */
993
1055
  export declare const AgentSessionDeletedEvent: S.Struct<{
994
1056
  /** Daemon-assigned ordinal, monotonically increasing per session. */
@@ -1466,6 +1528,19 @@ export declare const AgentEvent: S.Union<readonly [S.Struct<{
1466
1528
  readonly data: S.String;
1467
1529
  /** True when this is the last chunk. */
1468
1530
  readonly done: S.Boolean;
1531
+ }>, S.Struct<{
1532
+ /** The session this event belongs to (absent only before one exists). */
1533
+ readonly session_id: S.optional<S.String>;
1534
+ /** Daemon-assigned ordinal, monotonically increasing per session. */
1535
+ readonly seq: S.optional<S.Number>;
1536
+ /** Epoch milliseconds on the daemon. */
1537
+ readonly at: S.optional<S.Number>;
1538
+ /** Echo of the {@link AgentCommand} `id` this event answers, if any. */
1539
+ readonly command_id: S.optional<S.String>;
1540
+ readonly type: S.Literal<"attachment.status">;
1541
+ readonly sha256: S.String;
1542
+ readonly stored: S.Boolean;
1543
+ readonly received: S.Number;
1469
1544
  }>, S.Struct<{
1470
1545
  /** Daemon-assigned ordinal, monotonically increasing per session. */
1471
1546
  readonly seq: S.optional<S.Number>;
@@ -67,11 +67,17 @@ export const AGENT_HOOK_EVENTS = [
67
67
  "PreToolUse",
68
68
  "Stop",
69
69
  "SessionStart",
70
+ "UserPromptSubmit",
70
71
  ];
71
72
  /** Max inline attachments on one `send`. */
72
73
  export const AGENT_MAX_ATTACHMENTS = 8;
73
- /** Max base64 characters of one inline attachment. */
74
+ /** Max base64 characters of one `attachment.data` chunk. */
74
75
  export const AGENT_MAX_ATTACHMENT_BASE64_LENGTH = 6 * 1024 * 1024;
76
+ /**
77
+ * Decoded bytes of one `attachment_put` chunk. Small enough that a chunk
78
+ * never crowds the stream; each one is acknowledged before the next.
79
+ */
80
+ export const AGENT_ATTACHMENT_PUT_CHUNK_BYTES = 1024 * 1024;
75
81
  /**
76
82
  * Max characters of one absolute local-path attachment (same bound as a
77
83
  * session cwd). Path attachments are loopback-only and never cross the network.
@@ -125,24 +131,28 @@ export const AgentStreamOpenPayload = S.Struct({
125
131
  // ---------------------------------------------------------------------------
126
132
  // Commands (consumer → daemon)
127
133
  // ---------------------------------------------------------------------------
134
+ /** A cached attachment's id: the lowercase hex SHA-256 of its bytes. */
135
+ export const AGENT_ATTACHMENT_SHA256_PATTERN = /^[0-9a-f]{64}$/;
136
+ export const AgentAttachmentSha256 = S.String.check(S.isPattern(AGENT_ATTACHMENT_SHA256_PATTERN));
128
137
  /**
129
- * One attachment on `send`. Exactly one of `data` (base64, any transport) or
130
- * `path` (absolute local file, loopback agent socket only — the daemon rejects
131
- * `path` on mux/RTC). Both together are refused (same XOR pattern as
132
- * {@link AgentRespondCommand}).
138
+ * One attachment on `send`. Exactly one of `sha256` (bytes the consumer put
139
+ * into the device's attachment cache with {@link AgentAttachmentPutCommand},
140
+ * any transport) or `path` (an absolute file on the device, sent as a plain
141
+ * path in the prompt on any transport; only the loopback socket reads its
142
+ * bytes back). Both together are refused.
133
143
  */
134
144
  export const AgentAttachment = S.Struct({
135
145
  kind: S.Literals(["image", "file"]),
136
146
  name: S.optional(S.String.check(S.isMinLength(1), S.isMaxLength(256))),
137
147
  media_type: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
138
- /** Base64 bytes. Mutually exclusive with {@link path}. */
139
- data: S.optional(S.String.check(S.isMaxLength(AGENT_MAX_ATTACHMENT_BASE64_LENGTH))),
140
- /** Absolute local path; admitted only on the desktop loopback agent socket. */
148
+ /** A cached upload. Mutually exclusive with {@link path}. */
149
+ sha256: S.optional(AgentAttachmentSha256),
150
+ /** Absolute path on the device, admitted on any transport. */
141
151
  path: S.optional(S.String.check(S.isMinLength(1), S.isMaxLength(AGENT_MAX_ATTACHMENT_PATH_LENGTH))),
142
- }).check(S.makeFilter((attachment) => (attachment.data === undefined) !== (attachment.path === undefined), {
143
- message: "attachment carries exactly one of data / path",
152
+ }).check(S.makeFilter((attachment) => (attachment.sha256 === undefined) !== (attachment.path === undefined), {
153
+ message: "attachment carries exactly one of sha256 / path",
144
154
  }));
145
- /** True when the attachment carries an absolute local path instead of bytes. */
155
+ /** True when the attachment names a file on the device instead of a cached upload. */
146
156
  export const agentAttachmentHasPath = (attachment) => typeof attachment.path === "string";
147
157
  /**
148
158
  * Whether a path string can ride Claude's quoted `@"…"` mention: non-empty,
@@ -177,15 +187,13 @@ export const AgentAttachmentMeta = S.Struct({
177
187
  mime: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
178
188
  size: S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(0)),
179
189
  });
180
- /** Decoded-byte cap mirroring {@link AGENT_MAX_ATTACHMENT_BASE64_LENGTH}. */
181
- export const AGENT_MAX_ATTACHMENT_BYTES = Math.floor((AGENT_MAX_ATTACHMENT_BASE64_LENGTH * 3) / 4);
182
190
  /**
183
- * Cap for a `path` attachment on this Mac (loopback only). The send carries
184
- * no bytes, so {@link AGENT_MAX_ATTACHMENT_BYTES} doesn't apply; this bounds
185
- * the daemon's read when the transcript previews it (`attachment_get`,
186
- * chunked), so anything that can be sent can also be shown.
191
+ * Max bytes of one attachment, a cached upload or a path on the device alike.
192
+ * Uploads travel in {@link AGENT_ATTACHMENT_PUT_CHUNK_BYTES} chunks and
193
+ * previews come back chunked (`attachment_get`), so no single message carries
194
+ * a whole file.
187
195
  */
188
- export const AGENT_MAX_LOCAL_ATTACHMENT_BYTES = 64 * 1024 * 1024;
196
+ export const AGENT_MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
189
197
  /** Decision on an approval request (`request.opened`). */
190
198
  export const AgentRequestDecision = S.Literals([
191
199
  "accept",
@@ -301,6 +309,28 @@ export const AgentAttachmentGetCommand = S.Struct({
301
309
  id: S.optional(AgentCommandId),
302
310
  name: S.String.check(S.isMinLength(1), S.isMaxLength(256)),
303
311
  });
312
+ /**
313
+ * Put one chunk of an attachment into the device's attachment cache, keyed by
314
+ * the SHA-256 of the whole file. Chunks go in order from offset 0, each
315
+ * acknowledged by an {@link AgentAttachmentStatusEvent} before the next; the
316
+ * file is stored once `done` and its hash and size check out. A first chunk
317
+ * with empty `data` asks whether the file is already cached (the reply says
318
+ * `stored`), so a file is never sent twice. Any transport: these are the
319
+ * consumer's own bytes, never a file the device already had.
320
+ */
321
+ export const AgentAttachmentPutCommand = S.Struct({
322
+ type: S.Literal("attachment_put"),
323
+ id: S.optional(AgentCommandId),
324
+ sha256: AgentAttachmentSha256,
325
+ /** Total bytes of the file. */
326
+ size: S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(0), S.isLessThanOrEqualTo(AGENT_MAX_ATTACHMENT_BYTES)),
327
+ /** Decoded-byte offset of this chunk. */
328
+ offset: S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(0)),
329
+ /** Base64 of this chunk (at most {@link AGENT_ATTACHMENT_PUT_CHUNK_BYTES}). */
330
+ data: S.String.check(S.isMaxLength(AGENT_MAX_ATTACHMENT_BASE64_LENGTH)),
331
+ /** This chunk ends the file. */
332
+ done: S.Boolean,
333
+ });
304
334
  /**
305
335
  * A model id a running session can switch to: gateway ids and Claude aliases
306
336
  * (`ultra`, `sonnet`, `openai/gpt-5`, `claude-opus-4-5[1m]`). No whitespace or
@@ -352,6 +382,7 @@ export const AgentCommand = S.Union([
352
382
  AgentStartCommand,
353
383
  AgentAttachCommand,
354
384
  AgentSendCommand,
385
+ AgentAttachmentPutCommand,
355
386
  AgentSendNowCommand,
356
387
  AgentResumeQueueCommand,
357
388
  AgentCancelQueuedCommand,
@@ -686,6 +717,18 @@ export const AgentAttachmentDataEvent = S.Struct({
686
717
  /** True when this is the last chunk. */
687
718
  done: S.Boolean,
688
719
  });
720
+ /**
721
+ * Answer to every `attachment_put` (same `command_id`): `stored` once the
722
+ * file is in the cache (at once for a file already there), otherwise how many
723
+ * bytes the device holds so far, so the consumer sends the next chunk.
724
+ */
725
+ export const AgentAttachmentStatusEvent = S.Struct({
726
+ ...eventBase,
727
+ type: S.Literal("attachment.status"),
728
+ sha256: AgentAttachmentSha256,
729
+ stored: S.Boolean,
730
+ received: S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(0)),
731
+ });
689
732
  /** Answer to `delete_session`: the session is gone from the device. */
690
733
  export const AgentSessionDeletedEvent = S.Struct({
691
734
  ...eventBase,
@@ -729,6 +772,7 @@ export const AgentEvent = S.Union([
729
772
  AgentRuntimeWarningEvent,
730
773
  AgentRuntimeErrorEvent,
731
774
  AgentAttachmentDataEvent,
775
+ AgentAttachmentStatusEvent,
732
776
  AgentSessionDeletedEvent,
733
777
  AgentHistoryPageEvent,
734
778
  ]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openllmsh/sdk",
3
- "version": "2.10.15-alpha.7",
3
+ "version": "2.10.15-alpha.9",
4
4
  "private": false,
5
5
  "description": "The OpenLLM SDK: typed API contracts, wire-format adapters, the device tunnel, client-side vault crypto, the OpenAPI spec and MCP tools.",
6
6
  "keywords": [