xmemory 3.7.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.
- package/README.md +3 -0
- package/dist/cjs/client.js +369 -0
- package/dist/cjs/index.js +27 -0
- package/dist/cjs/instance.js +364 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/types.js +128 -0
- package/dist/esm/client.d.ts +73 -0
- package/dist/esm/index.d.ts +16 -0
- package/dist/esm/instance.d.ts +154 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/types.d.ts +813 -0
- package/package.json +21 -4
- /package/dist/{client.d.ts → cjs/client.d.ts} +0 -0
- /package/dist/{index.d.ts → cjs/index.d.ts} +0 -0
- /package/dist/{instance.d.ts → cjs/instance.d.ts} +0 -0
- /package/dist/{types.d.ts → cjs/types.d.ts} +0 -0
- /package/dist/{client.js → esm/client.js} +0 -0
- /package/dist/{index.js → esm/index.js} +0 -0
- /package/dist/{instance.js → esm/instance.js} +0 -0
- /package/dist/{types.js → esm/types.js} +0 -0
|
@@ -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
|
+
}
|