@openllmsh/sdk 2.10.15-alpha.8 → 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,27 +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` (an absolute file on the device, sent as a prompt mention on any
111
- * transport; only the loopback socket reads its bytes back). Both together
112
- * are refused (same XOR pattern as
113
- * {@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.
114
122
  */
115
123
  export declare const AgentAttachment: S.Struct<{
116
124
  readonly kind: S.Literals<readonly ["image", "file"]>;
117
125
  readonly name: S.optional<S.String>;
118
126
  readonly media_type: S.String;
119
- /** Base64 bytes. Mutually exclusive with {@link path}. */
120
- readonly data: S.optional<S.String>;
121
- /** Absolute path on the device: a prompt mention, admitted on any transport. */
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. */
122
130
  readonly path: S.optional<S.String>;
123
131
  }>;
124
132
  export type TAgentAttachment = S.Schema.Type<typeof AgentAttachment>;
125
- /** 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. */
126
134
  export declare const agentAttachmentHasPath: (attachment: TAgentAttachment) => attachment is TAgentAttachment & {
127
135
  readonly path: string;
128
- readonly data?: undefined;
136
+ readonly sha256?: undefined;
129
137
  };
130
138
  /**
131
139
  * Whether a path string can ride Claude's quoted `@"…"` mention: non-empty,
@@ -147,15 +155,13 @@ export declare const AgentAttachmentMeta: S.Struct<{
147
155
  readonly size: S.Number;
148
156
  }>;
149
157
  export type TAgentAttachmentMeta = S.Schema.Type<typeof AgentAttachmentMeta>;
150
- /** Decoded-byte cap mirroring {@link AGENT_MAX_ATTACHMENT_BASE64_LENGTH}. */
151
- export declare const AGENT_MAX_ATTACHMENT_BYTES: number;
152
158
  /**
153
- * Cap for a `path` attachment on this Mac (loopback only). The send carries
154
- * no bytes, so {@link AGENT_MAX_ATTACHMENT_BYTES} doesn't apply; this bounds
155
- * the daemon's read when the transcript previews it (`attachment_get`,
156
- * 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.
157
163
  */
158
- export declare const AGENT_MAX_LOCAL_ATTACHMENT_BYTES: number;
164
+ export declare const AGENT_MAX_ATTACHMENT_BYTES: number;
159
165
  /** Decision on an approval request (`request.opened`). */
160
166
  export declare const AgentRequestDecision: S.Literals<readonly ["accept", "accept_for_session", "decline", "cancel"]>;
161
167
  export type TAgentRequestDecision = S.Schema.Type<typeof AgentRequestDecision>;
@@ -208,9 +214,9 @@ export declare const AgentSendCommand: S.Struct<{
208
214
  readonly kind: S.Literals<readonly ["image", "file"]>;
209
215
  readonly name: S.optional<S.String>;
210
216
  readonly media_type: S.String;
211
- /** Base64 bytes. Mutually exclusive with {@link path}. */
212
- readonly data: S.optional<S.String>;
213
- /** Absolute path on the device: a prompt mention, admitted on any transport. */
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. */
214
220
  readonly path: S.optional<S.String>;
215
221
  }>>>;
216
222
  }>;
@@ -280,6 +286,29 @@ export declare const AgentAttachmentGetCommand: S.Struct<{
280
286
  readonly name: S.String;
281
287
  }>;
282
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>;
283
312
  /**
284
313
  * A model id a running session can switch to: gateway ids and Claude aliases
285
314
  * (`ultra`, `sonnet`, `openai/gpt-5`, `claude-opus-4-5[1m]`). No whitespace or
@@ -370,11 +399,23 @@ export declare const AgentCommand: S.Union<readonly [S.Struct<{
370
399
  readonly kind: S.Literals<readonly ["image", "file"]>;
371
400
  readonly name: S.optional<S.String>;
372
401
  readonly media_type: S.String;
373
- /** Base64 bytes. Mutually exclusive with {@link path}. */
374
- readonly data: S.optional<S.String>;
375
- /** Absolute path on the device: a prompt mention, admitted on any transport. */
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. */
376
405
  readonly path: S.optional<S.String>;
377
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;
378
419
  }>, S.Struct<{
379
420
  readonly type: S.Literal<"send_now">;
380
421
  readonly id: S.optional<S.String>;
@@ -990,6 +1031,26 @@ export declare const AgentAttachmentDataEvent: S.Struct<{
990
1031
  readonly done: S.Boolean;
991
1032
  }>;
992
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>;
993
1054
  /** Answer to `delete_session`: the session is gone from the device. */
994
1055
  export declare const AgentSessionDeletedEvent: S.Struct<{
995
1056
  /** Daemon-assigned ordinal, monotonically increasing per session. */
@@ -1467,6 +1528,19 @@ export declare const AgentEvent: S.Union<readonly [S.Struct<{
1467
1528
  readonly data: S.String;
1468
1529
  /** True when this is the last chunk. */
1469
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;
1470
1544
  }>, S.Struct<{
1471
1545
  /** Daemon-assigned ordinal, monotonically increasing per session. */
1472
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,25 +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` (an absolute file on the device, sent as a prompt mention on any
131
- * transport; only the loopback socket reads its bytes back). Both together
132
- * are refused (same XOR pattern as
133
- * {@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.
134
143
  */
135
144
  export const AgentAttachment = S.Struct({
136
145
  kind: S.Literals(["image", "file"]),
137
146
  name: S.optional(S.String.check(S.isMinLength(1), S.isMaxLength(256))),
138
147
  media_type: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
139
- /** Base64 bytes. Mutually exclusive with {@link path}. */
140
- data: S.optional(S.String.check(S.isMaxLength(AGENT_MAX_ATTACHMENT_BASE64_LENGTH))),
141
- /** Absolute path on the device: a prompt mention, admitted on any transport. */
148
+ /** A cached upload. Mutually exclusive with {@link path}. */
149
+ sha256: S.optional(AgentAttachmentSha256),
150
+ /** Absolute path on the device, admitted on any transport. */
142
151
  path: S.optional(S.String.check(S.isMinLength(1), S.isMaxLength(AGENT_MAX_ATTACHMENT_PATH_LENGTH))),
143
- }).check(S.makeFilter((attachment) => (attachment.data === undefined) !== (attachment.path === undefined), {
144
- 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",
145
154
  }));
146
- /** 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. */
147
156
  export const agentAttachmentHasPath = (attachment) => typeof attachment.path === "string";
148
157
  /**
149
158
  * Whether a path string can ride Claude's quoted `@"…"` mention: non-empty,
@@ -178,15 +187,13 @@ export const AgentAttachmentMeta = S.Struct({
178
187
  mime: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
179
188
  size: S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(0)),
180
189
  });
181
- /** Decoded-byte cap mirroring {@link AGENT_MAX_ATTACHMENT_BASE64_LENGTH}. */
182
- export const AGENT_MAX_ATTACHMENT_BYTES = Math.floor((AGENT_MAX_ATTACHMENT_BASE64_LENGTH * 3) / 4);
183
190
  /**
184
- * Cap for a `path` attachment on this Mac (loopback only). The send carries
185
- * no bytes, so {@link AGENT_MAX_ATTACHMENT_BYTES} doesn't apply; this bounds
186
- * the daemon's read when the transcript previews it (`attachment_get`,
187
- * 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.
188
195
  */
189
- export const AGENT_MAX_LOCAL_ATTACHMENT_BYTES = 64 * 1024 * 1024;
196
+ export const AGENT_MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
190
197
  /** Decision on an approval request (`request.opened`). */
191
198
  export const AgentRequestDecision = S.Literals([
192
199
  "accept",
@@ -302,6 +309,28 @@ export const AgentAttachmentGetCommand = S.Struct({
302
309
  id: S.optional(AgentCommandId),
303
310
  name: S.String.check(S.isMinLength(1), S.isMaxLength(256)),
304
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
+ });
305
334
  /**
306
335
  * A model id a running session can switch to: gateway ids and Claude aliases
307
336
  * (`ultra`, `sonnet`, `openai/gpt-5`, `claude-opus-4-5[1m]`). No whitespace or
@@ -353,6 +382,7 @@ export const AgentCommand = S.Union([
353
382
  AgentStartCommand,
354
383
  AgentAttachCommand,
355
384
  AgentSendCommand,
385
+ AgentAttachmentPutCommand,
356
386
  AgentSendNowCommand,
357
387
  AgentResumeQueueCommand,
358
388
  AgentCancelQueuedCommand,
@@ -687,6 +717,18 @@ export const AgentAttachmentDataEvent = S.Struct({
687
717
  /** True when this is the last chunk. */
688
718
  done: S.Boolean,
689
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
+ });
690
732
  /** Answer to `delete_session`: the session is gone from the device. */
691
733
  export const AgentSessionDeletedEvent = S.Struct({
692
734
  ...eventBase,
@@ -730,6 +772,7 @@ export const AgentEvent = S.Union([
730
772
  AgentRuntimeWarningEvent,
731
773
  AgentRuntimeErrorEvent,
732
774
  AgentAttachmentDataEvent,
775
+ AgentAttachmentStatusEvent,
733
776
  AgentSessionDeletedEvent,
734
777
  AgentHistoryPageEvent,
735
778
  ]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openllmsh/sdk",
3
- "version": "2.10.15-alpha.8",
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": [