xmemory 3.7.0 → 3.8.1

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,154 @@
1
+ /**
2
+ * InstanceHandle — scoped data operations on a single xmemory instance.
3
+ */
4
+ import type { SetupFormatValue, AgentSetupResult, ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteMutation, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
5
+ export declare class DescribeResult {
6
+ readonly instanceId: string;
7
+ readonly instanceName: string;
8
+ readonly about: string;
9
+ readonly schemaSummary: string;
10
+ readonly tools: readonly ToolDescription[];
11
+ /**
12
+ * What this memory is for. This is the instance's description, under the name
13
+ * the agent-facing surfaces give it.
14
+ */
15
+ readonly purpose: string | null;
16
+ /**
17
+ * The standing preference set for this memory, rendered verbatim.
18
+ *
19
+ * "owner" is the wire field's name, not a verified claim about authorship:
20
+ * anyone holding edit permission on the instance can set this, including an
21
+ * agent that was asked to. {@link asText} therefore labels it by provenance.
22
+ */
23
+ readonly ownerInstructions: string | null;
24
+ /**
25
+ * Generated from the schema; `null` until it has been generated, and cleared
26
+ * again by a schema change. Not folded into {@link asText} — it overlaps
27
+ * `schemaSummary`, which is already there, and a prompt gains nothing from
28
+ * being told twice.
29
+ */
30
+ readonly usageBrief: string | null;
31
+ constructor(raw: RawDescribeResult);
32
+ /**
33
+ * Plain-text representation suitable for injecting into an LLM system prompt.
34
+ *
35
+ * Includes `purpose` and `ownerInstructions` when the instance has them;
36
+ * `usageBrief` is deliberately left out (read the property if you want it).
37
+ *
38
+ * Both of those are free text set by anyone holding edit permission on the
39
+ * instance, so each is labelled with where it came from and how much weight it
40
+ * deserves rather than presented as if this library authored it. The labels
41
+ * state provenance; they are not a security boundary, and a caller embedding
42
+ * this in a system prompt is still handling text it does not control.
43
+ *
44
+ * By default, tools are presented as method calls (matching the SDK).
45
+ * Set `includeHttp` to `true` to also show HTTP method and path for
46
+ * raw REST callers.
47
+ */
48
+ asText(options?: {
49
+ includeHttp?: boolean;
50
+ }): string;
51
+ /** Tool definitions in the Anthropic tool-use format. */
52
+ asAnthropicTools(): Record<string, unknown>[];
53
+ /** Tool definitions in the OpenAI function-calling format. */
54
+ asOpenaiTools(): Record<string, unknown>[];
55
+ }
56
+ export declare class InstanceHandle {
57
+ readonly id: string;
58
+ private readonly _requestOne;
59
+ private _describeCache;
60
+ private _describeCacheAt;
61
+ private _describeTtlMs;
62
+ constructor(id: string, requestOne: RequestOneFn);
63
+ read(query: string, options?: ReadOptions): Promise<ReadResult>;
64
+ /**
65
+ * Write to this instance: extract from free text, or apply structured
66
+ * mutations. Pass a string to extract structured data from free-form text,
67
+ * or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
68
+ * delete edits (applied in array order; later mutations may reference
69
+ * objects created earlier in the batch, and a `null` value in a mutation's
70
+ * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
+ * to the text form.
72
+ *
73
+ * Pass `scope` — a `WriteScope` of concrete existing objects, each named by
74
+ * its user-defined primary key — to anchor a text write to them. Their current
75
+ * values are shown to the extractor so the write updates them instead of
76
+ * creating duplicates, and the write is then confined to the scope: it may
77
+ * only modify or delete the scoped objects and create new objects and
78
+ * relations anchored to them. A write that would touch any other existing
79
+ * object fails. The server accepts a scope with fast extraction only, and a
80
+ * scoped write additionally requires read permission on the instance, because
81
+ * the scoped objects' values are shown to the extractor.
82
+ */
83
+ write(text: string, options?: WriteOptions): Promise<WriteResult>;
84
+ write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
85
+ /**
86
+ * Submit a write job and return immediately with a `write_id` for polling.
87
+ * Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
88
+ * the same `scope`. A scope violation is reported by {@link writeStatus} as a
89
+ * failed write.
90
+ */
91
+ writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
92
+ writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
93
+ writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
94
+ extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
95
+ getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
96
+ /**
97
+ * Return the current consolidated schema-improvement proposal (step 1).
98
+ *
99
+ * The result's `proposal.proposal_version` is the optimistic-concurrency
100
+ * token you pass to `decideSuggestions` / `applyPendingDecisions`. When
101
+ * `status === "evolution_in_progress"`, back off for `retry_after_seconds`
102
+ * and retry instead of blocking on the in-flight migration.
103
+ */
104
+ reviewSuggestions(options?: SuggestionRequestOptions): Promise<ReviewSuggestionsResult>;
105
+ /**
106
+ * Record accept/reject/defer decisions for proposal items, in bulk (step 2).
107
+ *
108
+ * `proposalVersion` must be the token from the latest `reviewSuggestions`; a
109
+ * stale token throws `XmemoryAPIError` with `code === "stale_proposal_version"`.
110
+ * The result's `next_proposal_version` can be passed straight to
111
+ * `applyPendingDecisions`.
112
+ */
113
+ decideSuggestions(proposalVersion: string, decisions: DecisionInput[], options?: SuggestionRequestOptions): Promise<DecideSuggestionsResult>;
114
+ /**
115
+ * Commit accepted decisions as a single migration (step 3).
116
+ *
117
+ * `status === "nothing_to_apply"` means no accepted items were left. A stale
118
+ * `proposalVersion` or an unmet dependency throws `XmemoryAPIError`
119
+ * (`code === "stale_proposal_version"` / `"dependency_closure_failed"`).
120
+ */
121
+ applyPendingDecisions(proposalVersion: string, options?: SuggestionRequestOptions): Promise<ApplyPendingDecisionsResult>;
122
+ /**
123
+ * Return the agent-facing tool descriptions for this instance.
124
+ *
125
+ * The instance's schema comes back in `DescribeResult.schemaSummary`.
126
+ *
127
+ * Results are cached locally with a TTL (default 5 min).
128
+ * Call `clearDescribeCache()` to force a refresh.
129
+ */
130
+ describe(options?: RequestOptions): Promise<DescribeResult>;
131
+ /**
132
+ * How to connect *this* instance somewhere else, most likely surface first.
133
+ *
134
+ * Answers "how do I also reach this memory on my desktop, or in another editor" —
135
+ * not how to reach it from here, which this handle already does. The same payload
136
+ * `get_setup_instructions` serves over MCP and `xmemcli instance setup` prints.
137
+ *
138
+ * **Carries no credential.** The steps tell a reader to sign in themselves, out of
139
+ * band, so nothing returned here is a secret.
140
+ *
141
+ * Not cached, unlike `describe()`: it is computed from the instance's current
142
+ * metadata, so an owner who edits a surface hint expects the next call to show it.
143
+ *
144
+ * `format: SetupFormat.PROJECT` additionally returns the files a customer commits so a
145
+ * whole team gets this instance. Read `result.format` rather than assuming: a server
146
+ * older than that parameter ignores it, answers 200, and names no format at all, so
147
+ * `undefined` is the signal that this deployment predates the project rendering.
148
+ */
149
+ setupInstructions(options?: RequestOptions & {
150
+ format?: SetupFormatValue;
151
+ }): Promise<AgentSetupResult>;
152
+ /** Clear the cached describe result so the next `describe()` call fetches fresh data. */
153
+ clearDescribeCache(): void;
154
+ }
@@ -193,8 +193,21 @@ function buildJsonSchemaProps(params) {
193
193
  * exactly the deployments that have no link — the case the comparison exists for.
194
194
  * Same treatment `read` already gives `reader_results`.
195
195
  */
196
+ /**
197
+ * An *own* property of a decoded response, or `undefined`.
198
+ *
199
+ * A response is JSON, so a field the server omitted is answered by
200
+ * `Object.prototype` — and normalizing with `result.field ?? default` then writes
201
+ * that inherited value back as an own property, where nothing downstream can tell
202
+ * it apart from something the server actually sent. Prototype pollution anywhere in
203
+ * the process could fabricate sub-answers or a trace id this way.
204
+ */
205
+ function own(result, key) {
206
+ return Object.hasOwn(result, key) ? result[key] : undefined;
207
+ }
196
208
  function withConsoleUrl(result) {
197
- return { ...result, console_url: result.console_url ?? null };
209
+ const url = own(result, "console_url");
210
+ return { ...result, console_url: typeof url === "string" ? url : null };
198
211
  }
199
212
  export class InstanceHandle {
200
213
  id;
@@ -226,7 +239,17 @@ export class InstanceHandle {
226
239
  body,
227
240
  timeoutMs: options?.timeoutMs,
228
241
  });
229
- return withConsoleUrl({ ...result, reader_results: result.reader_results ?? [] });
242
+ // Every documented field set explicitly, so each one is an *own* property of
243
+ // what callers get back. Spreading alone leaves an omitted field to be answered
244
+ // by `Object.prototype` when the caller reads it.
245
+ const readerResults = own(result, "reader_results");
246
+ const traceId = own(result, "trace_id");
247
+ return withConsoleUrl({
248
+ ...result,
249
+ reader_result: own(result, "reader_result") ?? null,
250
+ reader_results: Array.isArray(readerResults) ? readerResults : [],
251
+ trace_id: typeof traceId === "string" ? traceId : null,
252
+ });
230
253
  }
231
254
  async write(input, options) {
232
255
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write`, { body: buildWriteBody(input, options), timeoutMs: options?.timeoutMs }));
@@ -238,7 +261,8 @@ export class InstanceHandle {
238
261
  });
239
262
  // `trace_id` is normalized here as well because this result declares it for the
240
263
  // first time, and the wire omits it exactly as it omits the console link.
241
- return withConsoleUrl({ ...result, trace_id: result.trace_id ?? null });
264
+ const traceId = own(result, "trace_id");
265
+ return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
242
266
  }
243
267
  async writeStatus(writeId, options) {
244
268
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
@@ -0,0 +1 @@
1
+ {"type":"module"}