xmemory 3.6.0 → 3.8.0

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.
@@ -0,0 +1,813 @@
1
+ /**
2
+ * Types, enums, and error classes for the xmemory API.
3
+ */
4
+ export declare const SchemaType: {
5
+ readonly YML: 0;
6
+ readonly JSON: 1;
7
+ };
8
+ export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
9
+ export type ExtractionLogic = "fast" | "deep";
10
+ export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
11
+ /**
12
+ * One concrete object a scoped read or a scoped write may touch. Identify it by
13
+ * `type` (PascalCase class name or snake_case table name) plus its user-defined
14
+ * primary `key`, with one entry per primary-key field. Only objects of a type
15
+ * that has a user-defined primary key can be scoped.
16
+ */
17
+ export interface ScopeObject {
18
+ type: string;
19
+ key: Record<string, string | number | boolean>;
20
+ }
21
+ /** Which relations a scoped read may traverse. */
22
+ export type RelationsScope = "no_relations" | "all_relations";
23
+ /**
24
+ * A read's scope: the concrete `objects` it may touch, plus relation policy.
25
+ * `relationsScope` is `no_relations` (objects only) by default; `all_relations`
26
+ * also exposes the relations among the in-scope `objects`.
27
+ */
28
+ export interface ReadScope {
29
+ objects: ScopeObject[];
30
+ relationsScope?: RelationsScope;
31
+ }
32
+ /**
33
+ * A write's scope: the concrete existing `objects` the write is anchored to.
34
+ * Their current values are shown to the extractor so the write updates them
35
+ * instead of creating duplicates, and the write is then confined to them — it
36
+ * may only modify or delete the scoped objects and create new objects and
37
+ * relations anchored to them. Unlike `ReadScope` there is no relation policy:
38
+ * the relations among the scoped objects always accompany the hint.
39
+ */
40
+ export interface WriteScope {
41
+ objects: ScopeObject[];
42
+ }
43
+ export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
44
+ export declare class XmemoryAPIError extends Error {
45
+ readonly status?: number | undefined;
46
+ /**
47
+ * Structured error code when the server returned one. **Branch on this,
48
+ * not on the bare HTTP `status`** — the same status can mean different
49
+ * things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
50
+ * exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
51
+ * velocity limit — retryable with backoff, honour `retryAfter`). For the
52
+ * schema-evolution endpoints this is the `error_type` discriminator
53
+ * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
54
+ * Pattern match on this instead of parsing the message.
55
+ */
56
+ readonly code?: string | undefined;
57
+ /**
58
+ * Optional structured `details` payload attached to some errors. For
59
+ * `"QUOTA_EXCEEDED"` this carries `kind`
60
+ * (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
61
+ * `retry_after_seconds` (`number | null`).
62
+ */
63
+ readonly details?: (Record<string, unknown> | null) | undefined;
64
+ /**
65
+ * The HTTP `Retry-After` response header, in seconds, when the server sent
66
+ * one — e.g. on `429 RATE_LIMITED`, or a resettable `402 QUOTA_EXCEEDED`.
67
+ * This is the transport-level header value; for quota errors the same hint
68
+ * may also appear as `details.retry_after_seconds`. Surfaced for callers
69
+ * that implement their own backoff — the client does not retry on its own.
70
+ */
71
+ readonly retryAfter?: number | undefined;
72
+ constructor(message: string, status?: number | undefined,
73
+ /**
74
+ * Structured error code when the server returned one. **Branch on this,
75
+ * not on the bare HTTP `status`** — the same status can mean different
76
+ * things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
77
+ * exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
78
+ * velocity limit — retryable with backoff, honour `retryAfter`). For the
79
+ * schema-evolution endpoints this is the `error_type` discriminator
80
+ * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
81
+ * Pattern match on this instead of parsing the message.
82
+ */
83
+ code?: string | undefined,
84
+ /**
85
+ * Optional structured `details` payload attached to some errors. For
86
+ * `"QUOTA_EXCEEDED"` this carries `kind`
87
+ * (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
88
+ * `retry_after_seconds` (`number | null`).
89
+ */
90
+ details?: (Record<string, unknown> | null) | undefined,
91
+ /**
92
+ * The HTTP `Retry-After` response header, in seconds, when the server sent
93
+ * one — e.g. on `429 RATE_LIMITED`, or a resettable `402 QUOTA_EXCEEDED`.
94
+ * This is the transport-level header value; for quota errors the same hint
95
+ * may also appear as `details.retry_after_seconds`. Surfaced for callers
96
+ * that implement their own backoff — the client does not retry on its own.
97
+ */
98
+ retryAfter?: number | undefined);
99
+ }
100
+ export declare class XmemoryHealthCheckError extends XmemoryAPIError {
101
+ constructor(message: string, status?: number);
102
+ }
103
+ export interface ClusterInfo {
104
+ readonly id: string;
105
+ readonly org_id: string;
106
+ readonly name: string;
107
+ readonly description: string | null;
108
+ }
109
+ export interface InstanceInfo {
110
+ readonly id: string;
111
+ readonly cluster_id: string;
112
+ readonly name: string;
113
+ readonly description: string | null;
114
+ readonly data_schema: Record<string, unknown> | null;
115
+ readonly agent_surfaces?: string[] | null;
116
+ readonly agent_default_binding_tier?: string | null;
117
+ readonly agent_engagement_hints?: string[] | null;
118
+ readonly agent_owner_instructions?: string | null;
119
+ readonly agent_owner_instructions_epoch?: number;
120
+ readonly migration_id?: string | null;
121
+ readonly prior_version?: number | null;
122
+ readonly new_version?: number | null;
123
+ readonly migration_warnings?: string[] | null;
124
+ }
125
+ /**
126
+ * An agent surface an instance is expected to be used from.
127
+ *
128
+ * Advisory: it seeds what a connect flow leads with, and grants nothing. Offered
129
+ * for writing the hint; reads stay plain strings so a surface added to the server
130
+ * after this release is returned rather than rejected.
131
+ */
132
+ export declare const AgentSurface: {
133
+ readonly CLAUDE_CODE: "claude_code";
134
+ readonly CODEX: "codex";
135
+ readonly CLAUDE_DESKTOP: "claude_desktop";
136
+ readonly CHATGPT: "chatgpt";
137
+ };
138
+ export type AgentSurfaceValue = (typeof AgentSurface)[keyof typeof AgentSurface];
139
+ /**
140
+ * How prominently a bound instance should participate in an agent session.
141
+ *
142
+ * `AUTOLOAD` proposes injecting the instance's context at session start;
143
+ * `AVAILABLE` proposes a one-line mention an agent can act on when relevant.
144
+ * A default for a binding only — the client-side binding is authoritative.
145
+ */
146
+ export declare const BindingTier: {
147
+ readonly AUTOLOAD: "autoload";
148
+ readonly AVAILABLE: "available";
149
+ };
150
+ export type BindingTierValue = (typeof BindingTier)[keyof typeof BindingTier];
151
+ export interface InstanceSchemaInfo {
152
+ readonly data_schema: Record<string, unknown>;
153
+ }
154
+ /**
155
+ * One sub-query and its own answer, in the requested read mode. Appears in
156
+ * {@link ReadResult.reader_results} when the server decomposed a composite query
157
+ * into independent sub-queries.
158
+ */
159
+ export interface TaggedReaderResult {
160
+ readonly sub_query: string;
161
+ readonly reader_result: unknown;
162
+ /**
163
+ * A user-safe message set when this sub-query could not be answered while the
164
+ * others still were (partial tolerance); `null` otherwise.
165
+ */
166
+ readonly error: string | null;
167
+ }
168
+ export interface ReadResult {
169
+ readonly trace_id: string | null;
170
+ /** Deep link to this read's trace in the console; `null` if no console is configured. */
171
+ readonly console_url: string | null;
172
+ readonly reader_result: unknown;
173
+ /**
174
+ * Per-sub-query answers when the server decomposed the query into independent
175
+ * sub-queries — one entry per sub-query, so a single-intent query decomposes
176
+ * to exactly one. `reader_result` above stays the combined back-compat value.
177
+ * Always an array: a server without question decomposition (or with it
178
+ * disabled) omits the field on the wire and the client normalizes it to `[]`,
179
+ * so the array is empty regardless of how many questions the query held.
180
+ */
181
+ readonly reader_results: readonly TaggedReaderResult[];
182
+ }
183
+ export interface WriteResult {
184
+ readonly write_id: string;
185
+ readonly trace_id: string | null;
186
+ /** Deep link to this write's trace in the console; `null` if no console is configured. */
187
+ readonly console_url: string | null;
188
+ /** What the write did, grouped into `created` / `updated` / `deleted`. */
189
+ readonly changes: unknown;
190
+ }
191
+ export interface AsyncWriteResult {
192
+ readonly write_id: string;
193
+ /** Trace id for the queued write, echoed by the server; `null` if it sent none. */
194
+ readonly trace_id: string | null;
195
+ /** Deep link to this write's trace in the console; `null` if no console is configured. */
196
+ readonly console_url: string | null;
197
+ }
198
+ export interface WriteStatusResult {
199
+ readonly write_id: string;
200
+ readonly write_status: WriteQueueStatus;
201
+ /** Deep link to the underlying write's trace; `null` if no console is configured. */
202
+ readonly console_url: string | null;
203
+ readonly error_detail: string | null;
204
+ readonly completed_at: string | null;
205
+ }
206
+ export interface ExtractResult {
207
+ readonly trace_id: string | null;
208
+ /** Deep link to this extraction's trace in the console; `null` if no console is configured. */
209
+ readonly console_url: string | null;
210
+ readonly objects_extracted: unknown;
211
+ }
212
+ export interface GenerateSchemaResult {
213
+ readonly data_schema: Record<string, unknown>;
214
+ }
215
+ export interface RelationEndpoint {
216
+ /** Relation role name from the instance schema. */
217
+ object_name: string;
218
+ /** Endpoint identity: user primary-key fields (field -> value), or `{ xuid: ... }`. */
219
+ key?: Record<string, unknown>;
220
+ }
221
+ /** Create an object: `key` holds the user primary-key fields (no `xuid` — it is
222
+ * generated server-side), `values` the remaining field values. */
223
+ export interface ObjectCreatePayload {
224
+ key?: Record<string, unknown>;
225
+ values?: Record<string, unknown>;
226
+ }
227
+ /** Update an object identified by `key` (primary-key fields or `{ xuid: ... }`).
228
+ * A `null` value in `values` clears that field. */
229
+ export interface ObjectUpdatePayload {
230
+ key: Record<string, unknown>;
231
+ values: Record<string, unknown>;
232
+ }
233
+ /** Delete the object identified by `key` (primary-key fields or `{ xuid: ... }`). */
234
+ export interface ObjectDeletePayload {
235
+ key: Record<string, unknown>;
236
+ }
237
+ /** Create a relation between the `endpoints`, with optional own-field `values`. */
238
+ export interface RelationCreatePayload {
239
+ endpoints: RelationEndpoint[];
240
+ values?: Record<string, unknown>;
241
+ }
242
+ /** Update a relation's own fields. Address it by `endpoints`, or by
243
+ * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
244
+ * clears that field. */
245
+ export interface RelationUpdatePayload {
246
+ key?: Record<string, unknown>;
247
+ endpoints?: RelationEndpoint[];
248
+ values: Record<string, unknown>;
249
+ }
250
+ /** Delete relation(s) matched by `endpoints` (a subset is allowed) or by
251
+ * `key: { xuid: ... }`. Deleting more than one matched row requires
252
+ * `allow_bulk_delete: true`. */
253
+ export interface RelationDeletePayload {
254
+ key?: Record<string, unknown>;
255
+ endpoints?: RelationEndpoint[];
256
+ allow_bulk_delete?: boolean;
257
+ }
258
+ export type ObjectMutationBody = {
259
+ object_type: string;
260
+ } & ({
261
+ create: ObjectCreatePayload;
262
+ update?: never;
263
+ delete?: never;
264
+ } | {
265
+ update: ObjectUpdatePayload;
266
+ create?: never;
267
+ delete?: never;
268
+ } | {
269
+ delete: ObjectDeletePayload;
270
+ create?: never;
271
+ update?: never;
272
+ });
273
+ export type RelationMutationBody = {
274
+ relation_type: string;
275
+ } & ({
276
+ create: RelationCreatePayload;
277
+ update?: never;
278
+ delete?: never;
279
+ } | {
280
+ update: RelationUpdatePayload;
281
+ create?: never;
282
+ delete?: never;
283
+ } | {
284
+ delete: RelationDeletePayload;
285
+ create?: never;
286
+ update?: never;
287
+ });
288
+ export type WriteMutation = {
289
+ object_mutation: ObjectMutationBody;
290
+ relation_mutation?: never;
291
+ } | {
292
+ relation_mutation: RelationMutationBody;
293
+ object_mutation?: never;
294
+ };
295
+ export type FieldType = "str" | "string" | "int" | "integer" | "float" | "bool" | "boolean";
296
+ export type OnDelete = "nullify" | "cascade";
297
+ export type CastStrategy = "safe_implicit" | "explicit_using" | "lossy";
298
+ export type DecisionKind = "accept" | "reject" | "defer";
299
+ export type MigrationSource = "direct" | "suggestion_engine";
300
+ export type DefaultValue = string | number | boolean | null;
301
+ export type EnumValues = Array<string | number | boolean> | null;
302
+ export interface FieldSpec {
303
+ name: string;
304
+ type: FieldType;
305
+ required?: boolean;
306
+ description?: string | null;
307
+ default?: DefaultValue;
308
+ enum?: EnumValues;
309
+ }
310
+ export interface AddObject {
311
+ op_type: "add_object";
312
+ name: string;
313
+ description?: string | null;
314
+ primary_key: string[];
315
+ fields: FieldSpec[];
316
+ should_backfill?: boolean;
317
+ }
318
+ export interface RemoveObject {
319
+ op_type: "remove_object";
320
+ name: string;
321
+ }
322
+ export interface RenameObject {
323
+ op_type: "rename_object";
324
+ old_name: string;
325
+ new_name: string;
326
+ }
327
+ export interface ChangeObject {
328
+ op_type: "change_object";
329
+ name: string;
330
+ new_primary_key?: string[] | null;
331
+ new_description?: string | null;
332
+ }
333
+ export interface AddField {
334
+ op_type: "add_field";
335
+ object_name: string;
336
+ field_name: string;
337
+ field_type: FieldType;
338
+ required?: boolean;
339
+ description?: string | null;
340
+ default?: DefaultValue;
341
+ enum?: EnumValues;
342
+ should_backfill?: boolean;
343
+ }
344
+ export interface RemoveField {
345
+ op_type: "remove_field";
346
+ object_name: string;
347
+ field_name: string;
348
+ }
349
+ export interface RenameField {
350
+ op_type: "rename_field";
351
+ object_name: string;
352
+ old_name: string;
353
+ new_name: string;
354
+ }
355
+ export interface ChangeField {
356
+ op_type: "change_field";
357
+ object_name: string;
358
+ field_name: string;
359
+ new_type?: FieldType | null;
360
+ new_required?: boolean | null;
361
+ new_description?: string | null;
362
+ new_default?: DefaultValue;
363
+ new_enum?: EnumValues;
364
+ clear_default?: boolean;
365
+ clear_enum?: boolean;
366
+ cast_strategy?: CastStrategy | null;
367
+ using_expression?: string | null;
368
+ confirm_data_loss?: boolean;
369
+ }
370
+ export interface AddRelation {
371
+ op_type: "add_relation";
372
+ name: string;
373
+ description?: string | null;
374
+ objects: Record<string, string>;
375
+ keys?: Record<string, string[]> | null;
376
+ on_delete?: Record<string, OnDelete> | null;
377
+ should_backfill?: boolean;
378
+ }
379
+ export interface RemoveRelation {
380
+ op_type: "remove_relation";
381
+ name: string;
382
+ }
383
+ export interface RenameRelation {
384
+ op_type: "rename_relation";
385
+ old_name: string;
386
+ new_name: string;
387
+ }
388
+ export interface ChangeRelation {
389
+ op_type: "change_relation";
390
+ name: string;
391
+ new_keys?: Record<string, string[]> | null;
392
+ new_on_delete?: Record<string, OnDelete> | null;
393
+ new_description?: string | null;
394
+ }
395
+ export type MigrationOp = AddObject | RemoveObject | RenameObject | ChangeObject | AddField | RemoveField | RenameField | ChangeField | AddRelation | RemoveRelation | RenameRelation | ChangeRelation;
396
+ export interface MigrationPlan {
397
+ ops: MigrationOp[];
398
+ }
399
+ export interface EnhanceSchemaResult {
400
+ readonly data_schema: Record<string, unknown>;
401
+ readonly migration_plan: MigrationPlan | null;
402
+ readonly summary: string | null;
403
+ readonly warnings: Record<string, unknown>[];
404
+ readonly repair_log: Record<string, unknown>[];
405
+ }
406
+ export interface PlanSummary {
407
+ readonly count_by_op_type: Record<string, number>;
408
+ readonly total: number;
409
+ }
410
+ export interface DryRunResult {
411
+ readonly status: "ok";
412
+ readonly instance_id: string;
413
+ readonly current_version: number;
414
+ readonly statements: string[];
415
+ readonly warnings: string[];
416
+ readonly plan_summary: PlanSummary;
417
+ readonly requires_metadata_sync: boolean;
418
+ }
419
+ export interface MigrationRecord {
420
+ readonly id: string;
421
+ readonly applied_at: string;
422
+ readonly source: MigrationSource;
423
+ readonly decided_by: string | null;
424
+ readonly prior_version: number;
425
+ readonly new_version: number;
426
+ readonly ops: Record<string, unknown>[];
427
+ readonly ops_summary: PlanSummary;
428
+ readonly notes: string | null;
429
+ readonly yaml_before: string | null;
430
+ readonly yaml_after: string | null;
431
+ }
432
+ export interface ListMigrationsResult {
433
+ readonly status: "ok";
434
+ readonly instance_id: string;
435
+ readonly items: MigrationRecord[];
436
+ readonly next_before_id: string | null;
437
+ readonly has_more: boolean;
438
+ }
439
+ export interface GetMigrationResult {
440
+ readonly status: "ok";
441
+ readonly instance_id: string;
442
+ readonly record: MigrationRecord;
443
+ }
444
+ export interface ProposalItem {
445
+ readonly item_fingerprint: string;
446
+ /** Raw op dict (forward-compatible). Cast to `MigrationOp` when needed. */
447
+ readonly op: Record<string, unknown>;
448
+ readonly evidence_feedback_ids: string[];
449
+ readonly evidence_query_samples: string[];
450
+ readonly frequency: number;
451
+ readonly depends_on: string[];
452
+ readonly current_decision: string | null;
453
+ readonly rationale: string;
454
+ }
455
+ export interface ConsolidatedProposal {
456
+ readonly instance_id: string;
457
+ readonly proposal_version: string;
458
+ readonly schema_version: number;
459
+ readonly items: ProposalItem[];
460
+ readonly generated_at: string;
461
+ readonly notes: string[];
462
+ }
463
+ export interface ReviewSuggestionsResult {
464
+ readonly status: "ok" | "evolution_in_progress";
465
+ readonly instance_id: string;
466
+ readonly proposal: ConsolidatedProposal | null;
467
+ readonly retry_after_seconds: number | null;
468
+ }
469
+ export interface DecisionInput {
470
+ item_fingerprint: string;
471
+ decision: DecisionKind;
472
+ edits?: Record<string, unknown> | null;
473
+ }
474
+ export interface RecordedDecision {
475
+ readonly item_fingerprint: string;
476
+ readonly decision_id: string;
477
+ }
478
+ export interface DependencyWarning {
479
+ readonly kind: string;
480
+ readonly item_fingerprint: string;
481
+ readonly related_fingerprints: string[];
482
+ readonly related_summaries: string[];
483
+ readonly guidance: string;
484
+ }
485
+ export interface DecideSuggestionsResult {
486
+ readonly status: "ok";
487
+ readonly instance_id: string;
488
+ readonly decisions_recorded: RecordedDecision[];
489
+ readonly warnings: DependencyWarning[];
490
+ readonly next_proposal_version: string;
491
+ }
492
+ export interface ApplyPendingDecisionsResult {
493
+ readonly status: "ok" | "nothing_to_apply";
494
+ readonly instance_id: string;
495
+ readonly migration_id: string | null;
496
+ readonly prior_version: number;
497
+ readonly new_version: number;
498
+ readonly applied_items: string[];
499
+ readonly summary: string;
500
+ readonly warnings: string[];
501
+ readonly notes: string[];
502
+ }
503
+ export interface ToolParameterDescription {
504
+ readonly name: string;
505
+ readonly type: string;
506
+ readonly description: string;
507
+ readonly required: boolean;
508
+ readonly enum?: string[];
509
+ readonly default?: string;
510
+ }
511
+ export interface ToolDescription {
512
+ readonly name: string;
513
+ readonly description: string;
514
+ readonly when_to_use: string;
515
+ readonly parameters: ToolParameterDescription[];
516
+ readonly http_method: string;
517
+ readonly http_path: string;
518
+ }
519
+ export interface RawDescribeResult {
520
+ readonly instance_id: string;
521
+ readonly instance_name: string;
522
+ readonly about?: string;
523
+ readonly schema_summary: string;
524
+ readonly tools: ToolDescription[];
525
+ /**
526
+ * What this memory is for. This is the instance's description, under the name
527
+ * the agent-facing surfaces give it.
528
+ */
529
+ readonly purpose?: string | null;
530
+ /**
531
+ * The standing preference set for this memory. Rendered verbatim — never
532
+ * paraphrased or summarized — so a rule survives exactly as written. "owner"
533
+ * is the wire field's name, not a verified claim about authorship.
534
+ */
535
+ readonly owner_instructions?: string | null;
536
+ /**
537
+ * The server-generated counterpart to `purpose`: how this instance is actually
538
+ * used, derived from its schema. Absent until it has been generated, and
539
+ * cleared again by a schema change, so treat its absence as ordinary.
540
+ */
541
+ readonly usage_brief?: string | null;
542
+ }
543
+ export interface XmemoryClientOptions {
544
+ url?: string;
545
+ apiKey?: string;
546
+ /** @deprecated Use `apiKey` instead. Will be removed in a future release. */
547
+ token?: string;
548
+ timeoutMs?: number;
549
+ }
550
+ export interface RequestOptions {
551
+ timeoutMs?: number;
552
+ }
553
+ export interface ReadOptions {
554
+ readMode?: ReadMode;
555
+ /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
556
+ scope?: ReadScope;
557
+ traceId?: string;
558
+ timeoutMs?: number;
559
+ }
560
+ export interface WriteOptions {
561
+ extractionLogic?: ExtractionLogic;
562
+ diffEngine?: boolean;
563
+ /**
564
+ * Anchor a text write to a set of concrete existing objects, confining it to
565
+ * them. Text writes only — the `WriteMutation[]` overload takes
566
+ * `RequestOptions`, so the combination the server rejects will not compile.
567
+ */
568
+ scope?: WriteScope;
569
+ timeoutMs?: number;
570
+ }
571
+ export interface ExtractOptions {
572
+ extractionLogic?: ExtractionLogic;
573
+ timeoutMs?: number;
574
+ }
575
+ export interface CreateInstanceOptions {
576
+ description?: string;
577
+ schemaDescription?: string;
578
+ timeoutMs?: number;
579
+ }
580
+ export interface GenerateSchemaOptions {
581
+ currentYmlSchema?: string;
582
+ timeoutMs?: number;
583
+ }
584
+ /**
585
+ * Extra fields for `updateInstanceMetadata`.
586
+ *
587
+ * Omitting a field leaves the stored value exactly as it is; passing `null`
588
+ * clears it. The endpoint treats a field present in the body as a field to set,
589
+ * so nothing you do not name is ever sent.
590
+ */
591
+ export interface UpdateInstanceMetadataOptions {
592
+ /**
593
+ * The standing preference for how agents should use this instance, set by
594
+ * anyone holding edit permission on it. Rendered verbatim. Max 2000
595
+ * characters. This is the path to prefer for the field — it is the only one
596
+ * that carries `expectedOwnerInstructionsEpoch`.
597
+ */
598
+ agentOwnerInstructions?: string | null;
599
+ /**
600
+ * The `agent_owner_instructions_epoch` your edit was composed from. Send it and
601
+ * a save that raced someone else's edit is refused rather than overwriting it.
602
+ */
603
+ expectedOwnerInstructionsEpoch?: number;
604
+ timeoutMs?: number;
605
+ }
606
+ /**
607
+ * Fields for `patchInstanceMetadata`. Every one is optional and independent:
608
+ * omit it and the stored value is untouched, pass `null` to clear it.
609
+ */
610
+ export interface PatchInstanceMetadataOptions {
611
+ name?: string;
612
+ description?: string | null;
613
+ /** Advisory: seeds what a connect flow leads with, and grants nothing. */
614
+ agentSurfaces?: readonly string[] | null;
615
+ agentDefaultBindingTier?: string | null;
616
+ /**
617
+ * Short routing phrases ("a convention is learned or corrected"). The server
618
+ * caps them at 16 of at most 200 characters each.
619
+ */
620
+ agentEngagementHints?: readonly string[] | null;
621
+ /**
622
+ * Authoritative rather than advisory — it outranks generated text and is
623
+ * rendered verbatim wherever it is shown, not that its authorship is
624
+ * verified: anyone holding edit permission can set it, including an agent
625
+ * asked to. Max 2000 characters.
626
+ *
627
+ * Prefer `updateInstanceMetadata` for this field. This endpoint accepts no
628
+ * `expectedOwnerInstructionsEpoch`, so an edit composed from a value someone
629
+ * has since replaced overwrites theirs silently. The three hints above are
630
+ * last-writer-wins by design — a lost update there only re-proposes a
631
+ * suggestion — but a lost instruction is a rule that stops being enforced.
632
+ */
633
+ agentOwnerInstructions?: string | null;
634
+ timeoutMs?: number;
635
+ }
636
+ export interface UpdateInstanceSchemaOptions {
637
+ /** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
638
+ migrationPlan?: MigrationPlan | Record<string, unknown>;
639
+ /** Authorise ops that drop data (remove object/field, lossy type cast). */
640
+ confirmDestructive?: boolean;
641
+ timeoutMs?: number;
642
+ }
643
+ export interface DryRunMigrationOptions {
644
+ migrationPlan?: MigrationPlan | Record<string, unknown>;
645
+ confirmDestructive?: boolean;
646
+ timeoutMs?: number;
647
+ }
648
+ export interface ListMigrationsOptions {
649
+ limit?: number;
650
+ beforeId?: string;
651
+ includeYaml?: boolean;
652
+ timeoutMs?: number;
653
+ }
654
+ export interface GetMigrationOptions {
655
+ includeYaml?: boolean;
656
+ timeoutMs?: number;
657
+ }
658
+ export interface SuggestionRequestOptions {
659
+ /** Optional free-form session ID for end-to-end tracing. */
660
+ sessionId?: string;
661
+ timeoutMs?: number;
662
+ }
663
+ export interface ApiError {
664
+ readonly code: string;
665
+ readonly message: string;
666
+ readonly field?: string;
667
+ readonly resource_id?: string;
668
+ }
669
+ export interface RawApiResponse {
670
+ readonly ids?: string[];
671
+ readonly items?: unknown[];
672
+ readonly errors?: ApiError[];
673
+ }
674
+ export interface InternalRequestOptions {
675
+ body?: Record<string, unknown>;
676
+ params?: Record<string, string | string[]>;
677
+ timeoutMs?: number;
678
+ }
679
+ export type RequestOneFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T>;
680
+ export type RequestListFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T[]>;
681
+ export type RequestIdsFn = (method: string, path: string, options?: InternalRequestOptions) => Promise<string[]>;
682
+ export declare function buildInstanceSchema(schemaText: string, schemaType: SchemaTypeValue): Record<string, unknown>;
683
+ /**
684
+ * Which rendering of an instance's setup to ask for.
685
+ *
686
+ * `AGENT` answers "what do I run right now, here". `PROJECT` answers "what do I
687
+ * commit so my team does not each run it by hand" — the same instance, but the
688
+ * output is files rather than steps.
689
+ */
690
+ export declare const SetupFormat: {
691
+ readonly AGENT: "agent";
692
+ readonly PROJECT: "project";
693
+ };
694
+ export type SetupFormatValue = (typeof SetupFormat)[keyof typeof SetupFormat];
695
+ /**
696
+ * What kind of thing `AgentSetupStep.command` is.
697
+ *
698
+ * The field carries three different things — a shell command, an in-session slash
699
+ * command, and a bare URL — so a caller that runs all of them in a shell will try to
700
+ * execute a connector URL. Check this before running anything.
701
+ */
702
+ export declare const StepKind: {
703
+ readonly SHELL: "shell";
704
+ readonly SLASH: "slash";
705
+ readonly URL: "url";
706
+ };
707
+ export type StepKindValue = (typeof StepKind)[keyof typeof StepKind];
708
+ /**
709
+ * How a fragment combines with a file the repository may already have.
710
+ *
711
+ * Every fragment is a merge, never a file to overwrite: a repository that already has
712
+ * a `.claude/settings.json` has permissions, hooks and directory trust in it, and
713
+ * replacing it wholesale to add two keys destroys that. Both merges are idempotent —
714
+ * applying a fragment twice must leave the file as one application would, so an
715
+ * applier that *appends* is implementing neither.
716
+ */
717
+ export declare const FragmentMerge: {
718
+ readonly MERGE_JSON: "merge_json";
719
+ readonly MERGE_TOML: "merge_toml";
720
+ };
721
+ export type FragmentMergeValue = (typeof FragmentMerge)[keyof typeof FragmentMerge];
722
+ /** One action, with the command that performs it where there is one. */
723
+ export interface AgentSetupStep {
724
+ readonly description: string;
725
+ readonly command?: string | null;
726
+ /**
727
+ * Absent rather than guessed where the server names no kind, which is also what an
728
+ * older server sends. Read the absence as "not known to be a shell command".
729
+ *
730
+ * Widened with `(string & {})` so a kind added after this release is still typed,
731
+ * while the known values keep their autocomplete. A kind you do not recognise is not
732
+ * executable: this field exists because the command may be a slash command or a bare
733
+ * URL, so running an unknown kind in a shell is the mistake it prevents.
734
+ */
735
+ readonly kind?: StepKindValue | (string & {}) | null;
736
+ }
737
+ /** How to connect this instance from one agent surface. */
738
+ export interface AgentSetupSurface {
739
+ /**
740
+ * Deliberately a plain string rather than `AgentSurfaceValue`: a server newer than
741
+ * this release can name a surface it has never heard of, and narrowing the type here
742
+ * would make every new surface a breaking change for every older client.
743
+ */
744
+ readonly surface: string;
745
+ readonly label: string;
746
+ readonly steps: AgentSetupStep[];
747
+ /**
748
+ * What a person still has to do themselves — approve a command, complete a browser
749
+ * sign-in, trust a hook. Relay these: they are the consent the flow depends on.
750
+ */
751
+ readonly human_steps: string[];
752
+ }
753
+ /** One file a customer commits so their teammates do not each set this up. */
754
+ export interface ProjectFragment {
755
+ readonly path: string;
756
+ readonly purpose: string;
757
+ /**
758
+ * Widened like `AgentSetupStep.kind`: a merge strategy added after this release is
759
+ * still typed. One you do not recognise cannot be applied safely — leave the file
760
+ * alone and surface the fragment as a manual step.
761
+ */
762
+ readonly merge: FragmentMergeValue | (string & {});
763
+ readonly content: string;
764
+ }
765
+ /**
766
+ * The committable half of an instance's setup.
767
+ *
768
+ * `manual_steps` is not a leftover: a surface with no committable channel is not the
769
+ * same as one that was forgotten, and a payload that silently omitted it would read as
770
+ * the latter.
771
+ */
772
+ export interface ProjectSetup {
773
+ readonly fragments: ProjectFragment[];
774
+ readonly manual_steps: string[];
775
+ }
776
+ /**
777
+ * How to connect one instance, ordered for where it is likely to be used.
778
+ *
779
+ * The same payload the server's create response carries, the `get_setup_instructions`
780
+ * MCP tools serve and `xmemcli instance setup` prints. (This client's
781
+ * `admin.createInstance()` returns an `InstanceHandle` rather than that payload — call
782
+ * one of the setup methods for it.)
783
+ *
784
+ * **Carries no credential.** The steps tell a reader to sign in themselves, out of
785
+ * band, precisely so a key never lands in a transcript.
786
+ */
787
+ export interface AgentSetupResult {
788
+ readonly instance_id: string;
789
+ readonly instance_name: string;
790
+ readonly install_page_url: string;
791
+ /**
792
+ * Ordered most-likely-first, never filtered: a hint about where an instance will be
793
+ * used is not a restriction on where it may be.
794
+ */
795
+ readonly surfaces: AgentSetupSurface[];
796
+ /** One line to paste into an agent instead of running anything by hand. */
797
+ readonly paste_to_agent: string;
798
+ /**
799
+ * What the server actually rendered, which is not always what was asked for: a
800
+ * server older than the `format` parameter ignores it and still answers 200, so a
801
+ * caller asking for `PROJECT` can receive the agent payload with no error at all.
802
+ * Compare this against what you requested rather than inferring from `project`
803
+ * being absent.
804
+ *
805
+ * Optional rather than defaulted, because those older servers name no format at all
806
+ * and `undefined` is the useful signal: *this deployment predates the project
807
+ * rendering*. Defaulting it to `AGENT` here would report a format the server never
808
+ * claimed, and hide the one case a caller has to branch on.
809
+ */
810
+ readonly format?: SetupFormatValue | (string & {});
811
+ /** Present only when `format=project` was both requested and honoured. */
812
+ readonly project?: ProjectSetup | null;
813
+ }