@slashml/memory 1.0.16 → 1.1.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.
package/src/index.ts CHANGED
@@ -64,6 +64,8 @@ export interface MemoryClientOptions {
64
64
  org_id?: string;
65
65
  projectId?: string;
66
66
  project_id?: string;
67
+ runId?: string;
68
+ run_id?: string;
67
69
  agentId?: string;
68
70
  agent_id?: string;
69
71
  callerAgentId?: string;
@@ -86,6 +88,10 @@ export interface MemoryFilters {
86
88
  appId?: string | null;
87
89
  run_id?: string | null;
88
90
  runId?: string | null;
91
+ project_id?: string | null;
92
+ projectId?: string | null;
93
+ inherit_scopes?: boolean;
94
+ inheritScopes?: boolean;
89
95
  metadata?: Record<string, unknown> | null;
90
96
  filters?: Record<string, unknown> | null;
91
97
  redact_policy?: RedactPolicy;
@@ -208,6 +214,63 @@ export interface ConfigureAgentOptions {
208
214
  metadata?: Record<string, unknown>;
209
215
  }
210
216
 
217
+ export interface MintWorkerTokenOptions {
218
+ tier?: string;
219
+ run_id?: string | null;
220
+ runId?: string | null;
221
+ project_id?: string | null;
222
+ projectId?: string | null;
223
+ access_mode?: AccessMode;
224
+ accessMode?: AccessMode;
225
+ redact_policy?: RedactPolicy;
226
+ redactPolicy?: RedactPolicy;
227
+ redact_scope?: RedactScope;
228
+ redactScope?: RedactScope;
229
+ ttl_seconds?: number;
230
+ ttlSeconds?: number;
231
+ can_delegate?: boolean;
232
+ canDelegate?: boolean;
233
+ }
234
+
235
+ export interface PromoteRunOptions {
236
+ run_id?: string | null;
237
+ runId?: string | null;
238
+ target_project_id?: string | null;
239
+ targetProjectId?: string | null;
240
+ target_user_id?: string | null;
241
+ targetUserId?: string | null;
242
+ memory_ids?: string[] | null;
243
+ memoryIds?: string[] | null;
244
+ discard_unpromoted?: boolean;
245
+ discardUnpromoted?: boolean;
246
+ caller_agent_id?: string | null;
247
+ callerAgentId?: string | null;
248
+ }
249
+
250
+ export interface GuardToolsOptions {
251
+ client?: MemoryClient;
252
+ apiKey?: string;
253
+ api_key?: string;
254
+ baseUrl?: string;
255
+ base_url?: string;
256
+ userId?: string;
257
+ user_id?: string;
258
+ projectId?: string | null;
259
+ project_id?: string | null;
260
+ runId?: string | null;
261
+ run_id?: string | null;
262
+ callerAgentId?: string | null;
263
+ caller_agent_id?: string | null;
264
+ redactOutputs?: boolean;
265
+ redact_outputs?: boolean;
266
+ redactPolicy?: RedactPolicy;
267
+ redact_policy?: RedactPolicy;
268
+ onBlock?: "return_error" | "return_object" | "raise";
269
+ on_block?: "return_error" | "return_object" | "raise";
270
+ failMode?: "open" | "closed";
271
+ fail_mode?: "open" | "closed";
272
+ }
273
+
211
274
  export interface InterveneOptions {
212
275
  hook_event_name?: string;
213
276
  hookEventName?: string;
@@ -229,8 +292,14 @@ export interface InterveneOptions {
229
292
  userId?: string | null;
230
293
  project_id?: string | null;
231
294
  projectId?: string | null;
295
+ run_id?: string | null;
296
+ runId?: string | null;
232
297
  session_id?: string | null;
233
298
  sessionId?: string | null;
299
+ strict_pretool_block?: boolean;
300
+ strictPretoolBlock?: boolean;
301
+ inherit_scopes?: boolean;
302
+ inheritScopes?: boolean;
234
303
  model?: string;
235
304
  commit_writes?: boolean;
236
305
  commitWrites?: boolean;
@@ -275,6 +344,25 @@ export class SlashMLAPIError extends Error {
275
344
  }
276
345
  }
277
346
 
347
+ export class SlashMLToolBlockedError extends Error {
348
+ public readonly toolName: string;
349
+ public readonly ruleIds: string[];
350
+ public readonly rawResponse: Record<string, unknown>;
351
+
352
+ constructor(
353
+ toolName: string,
354
+ message: string,
355
+ ruleIds: string[] = [],
356
+ rawResponse: Record<string, unknown> = {},
357
+ ) {
358
+ super(message);
359
+ this.name = "SlashMLToolBlockedError";
360
+ this.toolName = toolName;
361
+ this.ruleIds = ruleIds;
362
+ this.rawResponse = rawResponse;
363
+ }
364
+ }
365
+
278
366
  function getEnv(name: string): string | undefined {
279
367
  const g = globalThis as unknown as { process?: { env?: Record<string, string | undefined> } };
280
368
  if (typeof g.process !== "undefined" && g.process.env) {
@@ -469,6 +557,57 @@ export class AgentsManager {
469
557
  `/v1/agents/${encodeURIComponent(String(agentId).trim())}/`,
470
558
  );
471
559
  }
560
+
561
+ public async mintToken(
562
+ agentId: string,
563
+ options: MintWorkerTokenOptions = {},
564
+ ): Promise<Record<string, unknown>> {
565
+ const effRunId = options.run_id ?? options.runId ?? this.client.runId;
566
+ const effProjectId = options.project_id ?? options.projectId ?? this.client.projectId;
567
+ const payload: Record<string, unknown> = {
568
+ tier: options.tier ?? "worker",
569
+ ttl_seconds: options.ttl_seconds ?? options.ttlSeconds ?? 7200,
570
+ can_delegate: Boolean(options.can_delegate ?? options.canDelegate ?? false),
571
+ };
572
+ if (effRunId) payload.run_id = effRunId;
573
+ if (effProjectId) payload.project_id = effProjectId;
574
+ const accessMode = options.access_mode ?? options.accessMode;
575
+ if (accessMode !== undefined) payload.access_mode = accessMode;
576
+ const redactPolicy = options.redact_policy ?? options.redactPolicy;
577
+ if (redactPolicy !== undefined) {
578
+ payload.redact_policy = normalizeRedactPolicy(redactPolicy);
579
+ }
580
+ const redactScope = options.redact_scope ?? options.redactScope;
581
+ if (redactScope !== undefined) payload.redact_scope = redactScope;
582
+ return this.client.request(
583
+ "POST",
584
+ `/v1/agents/${encodeURIComponent(String(agentId).trim())}/tokens`,
585
+ { jsonBody: payload },
586
+ );
587
+ }
588
+
589
+ public async mint_token(
590
+ agentId: string,
591
+ options: MintWorkerTokenOptions = {},
592
+ ): Promise<Record<string, unknown>> {
593
+ return this.mintToken(agentId, options);
594
+ }
595
+
596
+ public async revoke(agentId: string): Promise<Record<string, unknown>> {
597
+ return this.client.request(
598
+ "POST",
599
+ `/v1/agents/${encodeURIComponent(String(agentId).trim())}/revoke`,
600
+ { jsonBody: {} },
601
+ );
602
+ }
603
+
604
+ public async revokeAll(): Promise<Record<string, unknown>> {
605
+ return this.client.request("POST", "/v1/agents/revoke-all", { jsonBody: {} });
606
+ }
607
+
608
+ public async revoke_all(): Promise<Record<string, unknown>> {
609
+ return this.revokeAll();
610
+ }
472
611
  }
473
612
 
474
613
  export class MemoryClient {
@@ -476,6 +615,7 @@ export class MemoryClient {
476
615
  public readonly baseUrl: string;
477
616
  public readonly orgId: string | null;
478
617
  public readonly projectId: string | null;
618
+ public readonly runId: string | null;
479
619
  public readonly agentId: string | null;
480
620
  public readonly callerAgentId: string | null;
481
621
  public readonly redactPolicy: string | string[] | null;
@@ -484,6 +624,7 @@ export class MemoryClient {
484
624
  public readonly timeoutMs: number;
485
625
  public readonly project: ProjectManager;
486
626
  public readonly agents: AgentsManager;
627
+ public lastVaultRevision: number;
487
628
  private readonly fetchImpl: typeof fetch;
488
629
 
489
630
  constructor(options: MemoryClientOptions = {}) {
@@ -512,6 +653,11 @@ export class MemoryClient {
512
653
  options.caller_agent_id ??
513
654
  getEnv("SLASHML_AGENT_ID") ??
514
655
  null;
656
+ const rawRunId =
657
+ options.runId ??
658
+ options.run_id ??
659
+ getEnv("SLASHML_RUN_ID") ??
660
+ null;
515
661
  const rawRedactPolicy =
516
662
  options.redactPolicy ??
517
663
  options.redact_policy ??
@@ -527,6 +673,7 @@ export class MemoryClient {
527
673
  this.baseUrl = resolvedUrl.replace(/\/+$/, "");
528
674
  this.orgId = options.orgId || options.org_id || getEnv("SLASHML_ORG_ID") || null;
529
675
  this.projectId = options.projectId || options.project_id || getEnv("SLASHML_PROJECT_ID") || null;
676
+ this.runId = rawRunId && String(rawRunId).trim() ? String(rawRunId).trim() : null;
530
677
  this.agentId = rawAgentId && String(rawAgentId).trim() ? String(rawAgentId).trim() : null;
531
678
  this.callerAgentId = this.agentId;
532
679
  this.redactPolicy = normalizeRedactPolicy(rawRedactPolicy);
@@ -536,6 +683,7 @@ export class MemoryClient {
536
683
  : null;
537
684
  this.model = resolvedModel;
538
685
  this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
686
+ this.lastVaultRevision = 0;
539
687
  this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
540
688
  this.project = new ProjectManager(this);
541
689
  this.agents = new AgentsManager(this);
@@ -617,6 +765,9 @@ export class MemoryClient {
617
765
  if (this.projectId) {
618
766
  headers["X-SlashML-Project-Id"] = this.projectId;
619
767
  }
768
+ if (this.runId) {
769
+ headers["X-SlashML-Run-Id"] = this.runId;
770
+ }
620
771
  if (this.agentId) {
621
772
  headers["X-SlashML-Agent-Id"] = this.agentId;
622
773
  }
@@ -637,6 +788,18 @@ export class MemoryClient {
637
788
  signal: controller.signal,
638
789
  });
639
790
 
791
+ const revHdr =
792
+ response.headers && typeof response.headers.get === "function"
793
+ ? response.headers.get("x-slashml-vault-revision") ||
794
+ response.headers.get("X-SlashML-Vault-Revision")
795
+ : null;
796
+ if (revHdr) {
797
+ const parsedRev = Number.parseInt(String(revHdr).trim(), 10);
798
+ if (Number.isFinite(parsedRev) && parsedRev > this.lastVaultRevision) {
799
+ this.lastVaultRevision = parsedRev;
800
+ }
801
+ }
802
+
640
803
  const rawText = await response.text();
641
804
  let parsed: Record<string, unknown> = {};
642
805
  if (rawText) {
@@ -928,6 +1091,74 @@ export class MemoryClient {
928
1091
  return this.agents.delete(agentId);
929
1092
  }
930
1093
 
1094
+ public async mintWorkerToken(
1095
+ agentId: string,
1096
+ options: MintWorkerTokenOptions = {},
1097
+ ): Promise<Record<string, unknown>> {
1098
+ return this.agents.mintToken(agentId, options);
1099
+ }
1100
+
1101
+ public async mint_worker_token(
1102
+ agentId: string,
1103
+ options: MintWorkerTokenOptions = {},
1104
+ ): Promise<Record<string, unknown>> {
1105
+ return this.agents.mintToken(agentId, options);
1106
+ }
1107
+
1108
+ public async revokeAgentTokens(agentId: string): Promise<Record<string, unknown>> {
1109
+ return this.agents.revoke(agentId);
1110
+ }
1111
+
1112
+ public async revoke_agent_tokens(agentId: string): Promise<Record<string, unknown>> {
1113
+ return this.agents.revoke(agentId);
1114
+ }
1115
+
1116
+ public async revokeAllTokens(): Promise<Record<string, unknown>> {
1117
+ return this.agents.revokeAll();
1118
+ }
1119
+
1120
+ public async revoke_all_tokens(): Promise<Record<string, unknown>> {
1121
+ return this.agents.revokeAll();
1122
+ }
1123
+
1124
+ public async promoteRun(
1125
+ runIdOrOptions?: string | PromoteRunOptions,
1126
+ options: PromoteRunOptions = {},
1127
+ ): Promise<Record<string, unknown>> {
1128
+ const isStr = typeof runIdOrOptions === "string";
1129
+ const opts: PromoteRunOptions = isStr
1130
+ ? { ...options, run_id: runIdOrOptions }
1131
+ : { ...(runIdOrOptions ?? {}), ...options };
1132
+ const effRunId = opts.run_id ?? opts.runId ?? this.runId;
1133
+ if (!effRunId) {
1134
+ throw new SlashMLAPIError(
1135
+ 400,
1136
+ "runId is required for promoteRun (pass runId or set SLASHML_RUN_ID).",
1137
+ );
1138
+ }
1139
+ const payload: Record<string, unknown> = {
1140
+ run_id: effRunId,
1141
+ discard_unpromoted: Boolean(opts.discard_unpromoted ?? opts.discardUnpromoted ?? false),
1142
+ };
1143
+ const targetProject = opts.target_project_id ?? opts.targetProjectId ?? this.projectId;
1144
+ if (targetProject) payload.target_project_id = targetProject;
1145
+ const targetUser = opts.target_user_id ?? opts.targetUserId;
1146
+ if (targetUser) payload.target_user_id = targetUser;
1147
+ const memoryIds = opts.memory_ids ?? opts.memoryIds;
1148
+ if (memoryIds !== undefined && memoryIds !== null) payload.memory_ids = memoryIds;
1149
+ const headers = this.applyLifecycleDefaults(payload, {
1150
+ callerAgentId: opts.caller_agent_id ?? opts.callerAgentId,
1151
+ });
1152
+ return this.request("POST", "/v1/memory/promote", { jsonBody: payload, headers });
1153
+ }
1154
+
1155
+ public async promote_run(
1156
+ runIdOrOptions?: string | PromoteRunOptions,
1157
+ options: PromoteRunOptions = {},
1158
+ ): Promise<Record<string, unknown>> {
1159
+ return this.promoteRun(runIdOrOptions, options);
1160
+ }
1161
+
931
1162
  public async intervene(
932
1163
  textOrPayload: string | InterveneOptions,
933
1164
  options: InterveneOptions = {},
@@ -939,7 +1170,10 @@ export class MemoryClient {
939
1170
  const resolvedText = opts.text ?? opts.prompt ?? "";
940
1171
  const resolvedModel = opts.model ?? this.model;
941
1172
  const resolvedProjectId = opts.project_id ?? opts.projectId ?? this.projectId ?? null;
1173
+ const resolvedRunId = opts.run_id ?? opts.runId ?? this.runId ?? null;
942
1174
  const resolvedSessionId = opts.session_id ?? opts.sessionId ?? null;
1175
+ const strictBlock = opts.strict_pretool_block ?? opts.strictPretoolBlock;
1176
+ const inheritScopes = opts.inherit_scopes ?? opts.inheritScopes;
943
1177
  const lastAssistantMsg =
944
1178
  opts.last_assistant_message ?? opts.lastAssistantMessage ?? undefined;
945
1179
  const stopHookActive =
@@ -958,7 +1192,10 @@ export class MemoryClient {
958
1192
  tool_response: opts.tool_response ?? opts.toolResponse ?? null,
959
1193
  user_id: opts.user_id ?? opts.userId ?? "default",
960
1194
  ...(resolvedProjectId ? { project_id: resolvedProjectId } : {}),
1195
+ ...(resolvedRunId ? { run_id: resolvedRunId } : {}),
961
1196
  ...(resolvedSessionId ? { session_id: resolvedSessionId } : {}),
1197
+ ...(strictBlock !== undefined ? { strict_pretool_block: Boolean(strictBlock) } : {}),
1198
+ ...(inheritScopes !== undefined ? { inherit_scopes: Boolean(inheritScopes) } : {}),
962
1199
  model: resolvedModel,
963
1200
  commit_writes: opts.commit_writes ?? opts.commitWrites ?? true,
964
1201
  top_k: opts.top_k ?? opts.topK ?? 5,
@@ -1019,7 +1256,10 @@ export class MemoryClient {
1019
1256
  user_id: options.user_id ?? options.userId ?? null,
1020
1257
  agent_id: options.agent_id ?? options.agentId ?? null,
1021
1258
  app_id: options.app_id ?? options.appId ?? null,
1022
- run_id: options.run_id ?? options.runId ?? null,
1259
+ run_id: options.run_id ?? options.runId ?? this.runId ?? null,
1260
+ ...(options.project_id ?? options.projectId ?? this.projectId
1261
+ ? { project_id: options.project_id ?? options.projectId ?? this.projectId }
1262
+ : {}),
1023
1263
  metadata: options.metadata ?? {},
1024
1264
  infer: options.infer ?? true,
1025
1265
  model: this.model,
@@ -1046,12 +1286,16 @@ export class MemoryClient {
1046
1286
  const query = isObj ? queryOrOptions.query : queryOrOptions;
1047
1287
  const opts: SearchMemoryOptions = isObj ? queryOrOptions : options;
1048
1288
  const effectiveLimit = opts.top_k ?? opts.topK ?? opts.limit ?? 5;
1289
+ const inheritScopes = opts.inherit_scopes ?? opts.inheritScopes;
1290
+ const effProj = opts.project_id ?? opts.projectId ?? this.projectId;
1049
1291
  const payload: Record<string, unknown> = {
1050
1292
  query,
1051
1293
  user_id: opts.user_id ?? opts.userId ?? null,
1052
1294
  agent_id: opts.agent_id ?? opts.agentId ?? null,
1053
1295
  app_id: opts.app_id ?? opts.appId ?? null,
1054
- run_id: opts.run_id ?? opts.runId ?? null,
1296
+ run_id: opts.run_id ?? opts.runId ?? this.runId ?? null,
1297
+ ...(effProj ? { project_id: effProj } : {}),
1298
+ ...(inheritScopes !== undefined ? { inherit_scopes: Boolean(inheritScopes) } : {}),
1055
1299
  limit: effectiveLimit,
1056
1300
  top_k: effectiveLimit,
1057
1301
  filters: opts.filters ?? opts.metadata ?? null,
@@ -1082,6 +1326,7 @@ export class MemoryClient {
1082
1326
  options.redact_policy ?? options.redactPolicy ?? this.redactPolicy,
1083
1327
  );
1084
1328
  const effScope = options.redact_scope ?? options.redactScope ?? this.redactScope;
1329
+ const inheritScopes = options.inherit_scopes ?? options.inheritScopes;
1085
1330
  const headers = this.applyLifecycleDefaults(undefined, {
1086
1331
  callerAgentId: options.caller_agent_id ?? options.callerAgentId,
1087
1332
  });
@@ -1091,7 +1336,9 @@ export class MemoryClient {
1091
1336
  user_id: options.user_id ?? options.userId ?? undefined,
1092
1337
  agent_id: options.agent_id ?? options.agentId ?? undefined,
1093
1338
  app_id: options.app_id ?? options.appId ?? undefined,
1094
- run_id: options.run_id ?? options.runId ?? undefined,
1339
+ run_id: options.run_id ?? options.runId ?? this.runId ?? undefined,
1340
+ project_id: options.project_id ?? options.projectId ?? this.projectId ?? undefined,
1341
+ inherit_scopes: inheritScopes !== undefined ? Boolean(inheritScopes) : undefined,
1095
1342
  limit: options.limit ?? 100,
1096
1343
  redact_policy: Array.isArray(effPolicy) ? effPolicy.join(",") : (effPolicy ?? undefined),
1097
1344
  redact_scope: effScope ?? undefined,
@@ -1507,6 +1754,7 @@ export class Memory extends MemoryClient {
1507
1754
  (configDict.host as string),
1508
1755
  orgId: (configDict.org_id as string) || (configDict.orgId as string),
1509
1756
  projectId: (configDict.project_id as string) || (configDict.projectId as string),
1757
+ runId: (configDict.run_id as string) || (configDict.runId as string),
1510
1758
  agentId:
1511
1759
  (configDict.agent_id as string) ||
1512
1760
  (configDict.agentId as string) ||
@@ -1536,4 +1784,238 @@ export class SlashMLClient extends MemoryClient {}
1536
1784
  export class AsyncSlashMLMemory extends MemoryClient {}
1537
1785
  export class AsyncSlashMLClient extends MemoryClient {}
1538
1786
 
1787
+ function resolveGuardClient(options: GuardToolsOptions = {}): MemoryClient {
1788
+ if (options.client instanceof MemoryClient) {
1789
+ return options.client;
1790
+ }
1791
+ return new MemoryClient({
1792
+ apiKey: options.apiKey ?? options.api_key,
1793
+ baseUrl: options.baseUrl ?? options.base_url,
1794
+ projectId: options.projectId ?? options.project_id ?? undefined,
1795
+ runId: options.runId ?? options.run_id ?? undefined,
1796
+ agentId: options.callerAgentId ?? options.caller_agent_id ?? undefined,
1797
+ redactPolicy: options.redactPolicy ?? options.redact_policy,
1798
+ });
1799
+ }
1800
+
1801
+ function normalizeGuardInput(args: unknown[]): Record<string, unknown> {
1802
+ if (args.length === 0) return {};
1803
+ const first = args[0];
1804
+ if (first && typeof first === "object" && !Array.isArray(first)) {
1805
+ return { ...(first as Record<string, unknown>) };
1806
+ }
1807
+ if (args.length === 1) {
1808
+ return { input: first };
1809
+ }
1810
+ return { args };
1811
+ }
1812
+
1813
+ async function evaluateTsPretoolGuard(
1814
+ client: MemoryClient,
1815
+ toolName: string,
1816
+ toolInput: Record<string, unknown>,
1817
+ options: GuardToolsOptions,
1818
+ ): Promise<{
1819
+ blocked: boolean;
1820
+ message: string;
1821
+ ruleIds: string[];
1822
+ raw: Record<string, unknown>;
1823
+ }> {
1824
+ const failMode = String(options.failMode ?? options.fail_mode ?? "open").toLowerCase();
1825
+ const promptText = `${toolName} ${JSON.stringify(toolInput)}`;
1826
+ try {
1827
+ const res = await client.intervene(promptText, {
1828
+ hook_event_name: "PreToolUse",
1829
+ tool_name: toolName,
1830
+ tool_input: toolInput,
1831
+ user_id: options.userId ?? options.user_id ?? "default",
1832
+ project_id: options.projectId ?? options.project_id ?? client.projectId,
1833
+ run_id: options.runId ?? options.run_id ?? client.runId,
1834
+ strict_pretool_block: true,
1835
+ commit_writes: false,
1836
+ redact_policy: options.redactPolicy ?? options.redact_policy,
1837
+ caller_agent_id: options.callerAgentId ?? options.caller_agent_id ?? client.agentId,
1838
+ });
1839
+ const decision = String(
1840
+ res.action ?? res.intervention_severity ?? res.decision ?? "",
1841
+ ).toUpperCase();
1842
+ const sev = String(res.intervention_severity ?? "").toUpperCase();
1843
+ const hookEnv =
1844
+ res.hook_output && typeof res.hook_output === "object"
1845
+ ? (res.hook_output as Record<string, unknown>)
1846
+ : res;
1847
+ const hookOut =
1848
+ hookEnv.hookSpecificOutput && typeof hookEnv.hookSpecificOutput === "object"
1849
+ ? (hookEnv.hookSpecificOutput as Record<string, unknown>)
1850
+ : res.hookSpecificOutput && typeof res.hookSpecificOutput === "object"
1851
+ ? (res.hookSpecificOutput as Record<string, unknown>)
1852
+ : {};
1853
+ const perm = String(hookOut.permissionDecision ?? "").toLowerCase();
1854
+ const blocked = decision === "BLOCK" || sev === "BLOCK" || perm === "deny";
1855
+ if (!blocked) {
1856
+ return { blocked: false, message: "", ruleIds: [], raw: res };
1857
+ }
1858
+ let msg =
1859
+ String(hookOut.permissionDecisionReason ?? "").trim() ||
1860
+ String(res.intervention_message ?? "").trim() ||
1861
+ String(res.whisper ?? "").trim() ||
1862
+ String(res.reason ?? "").trim() ||
1863
+ `[SLASHML GUARDRAIL BLOCK] Tool '${toolName}' blocked by active policy.`;
1864
+ if (!msg.includes("[SLASHML GUARDRAIL BLOCK]")) {
1865
+ msg = `[SLASHML GUARDRAIL BLOCK] ${msg}`;
1866
+ }
1867
+ const rawIds = Array.isArray(res.violated_memory_ids)
1868
+ ? res.violated_memory_ids
1869
+ : Array.isArray(res.whispered_memory_ids)
1870
+ ? res.whispered_memory_ids
1871
+ : [];
1872
+ const ruleIds = rawIds.map((r) => String(r)).filter(Boolean);
1873
+ return { blocked: true, message: msg, ruleIds, raw: res };
1874
+ } catch (err) {
1875
+ if (err instanceof SlashMLAPIError && (err.statusCode === 401 || err.statusCode === 403)) {
1876
+ const msg = `[SLASHML GUARDRAIL BLOCK] Authorization rejected (${err.statusCode}) before executing '${toolName}': ${err.message}`;
1877
+ return { blocked: true, message: msg, ruleIds: [], raw: err.details };
1878
+ }
1879
+ if (failMode === "closed") {
1880
+ const msg = `[SLASHML GUARDRAIL BLOCK] Guardrail error in fail-closed mode for '${toolName}': ${
1881
+ err instanceof Error ? err.message : String(err)
1882
+ }`;
1883
+ return { blocked: true, message: msg, ruleIds: [], raw: {} };
1884
+ }
1885
+ return { blocked: false, message: "", ruleIds: [], raw: {} };
1886
+ }
1887
+ }
1888
+
1889
+ async function scrubTsToolOutput(
1890
+ client: MemoryClient,
1891
+ output: unknown,
1892
+ options: GuardToolsOptions,
1893
+ ): Promise<unknown> {
1894
+ const redactOutputs = options.redactOutputs ?? options.redact_outputs ?? true;
1895
+ if (!redactOutputs || output === null || output === undefined) {
1896
+ return output;
1897
+ }
1898
+ if (typeof output === "boolean" || typeof output === "number") {
1899
+ return output;
1900
+ }
1901
+ const effPolicy = normalizeRedactPolicy(
1902
+ options.redactPolicy ?? options.redact_policy ?? client.redactPolicy,
1903
+ );
1904
+ if (effPolicy === "off") {
1905
+ return output;
1906
+ }
1907
+ const isStructured = typeof output === "object";
1908
+ let rawText = "";
1909
+ if (typeof output === "string") {
1910
+ rawText = output;
1911
+ } else if (isStructured) {
1912
+ try {
1913
+ rawText = JSON.stringify(output);
1914
+ } catch {
1915
+ rawText = String(output);
1916
+ }
1917
+ } else {
1918
+ return output;
1919
+ }
1920
+ if (!rawText.trim()) {
1921
+ return output;
1922
+ }
1923
+ try {
1924
+ const res = await client.redact({
1925
+ text: rawText,
1926
+ redact_policy: effPolicy ?? undefined,
1927
+ caller_agent_id: options.callerAgentId ?? options.caller_agent_id ?? client.agentId ?? undefined,
1928
+ });
1929
+ const redactedText = res.redacted_text;
1930
+ if (typeof redactedText !== "string" || redactedText === rawText) {
1931
+ return output;
1932
+ }
1933
+ if (isStructured) {
1934
+ try {
1935
+ return JSON.parse(redactedText);
1936
+ } catch {
1937
+ return redactedText;
1938
+ }
1939
+ }
1940
+ return redactedText;
1941
+ } catch {
1942
+ const failMode = String(options.failMode ?? options.fail_mode ?? "open").toLowerCase();
1943
+ if (failMode === "closed") {
1944
+ return "[SLASHML REDACTION ERROR: OUTPUT WITHHELD]";
1945
+ }
1946
+ return output;
1947
+ }
1948
+ }
1949
+
1950
+ export function guardCallable<T extends (...args: any[]) => any>(
1951
+ fn: T,
1952
+ toolName = "tool",
1953
+ options: GuardToolsOptions = {},
1954
+ ): (...args: Parameters<T>) => Promise<unknown> {
1955
+ const client = resolveGuardClient(options);
1956
+ const onBlock = options.onBlock ?? options.on_block ?? "return_error";
1957
+ const resolvedName = toolName || fn.name || "tool";
1958
+ return async (...args: Parameters<T>): Promise<unknown> => {
1959
+ const toolInput = normalizeGuardInput(args);
1960
+ const verdict = await evaluateTsPretoolGuard(client, resolvedName, toolInput, options);
1961
+ if (verdict.blocked) {
1962
+ if (onBlock === "raise") {
1963
+ throw new SlashMLToolBlockedError(
1964
+ resolvedName,
1965
+ verdict.message,
1966
+ verdict.ruleIds,
1967
+ verdict.raw,
1968
+ );
1969
+ }
1970
+ if (onBlock === "return_object") {
1971
+ return { error: verdict.message, blocked: true, ruleIds: verdict.ruleIds };
1972
+ }
1973
+ return verdict.message;
1974
+ }
1975
+ const result = await fn(...args);
1976
+ return scrubTsToolOutput(client, result, options);
1977
+ };
1978
+ }
1979
+
1980
+ /**
1981
+ * 1-line runtime guardrail wrapper for Vercel AI SDK tool maps, LangChain.js tools, or functions.
1982
+ */
1983
+ export function guardTools<T>(tools: T, options: GuardToolsOptions = {}): T {
1984
+ const client = resolveGuardClient(options);
1985
+ const mergedOpts: GuardToolsOptions = { ...options, client };
1986
+
1987
+ const wrapItem = (item: any, explicitName?: string): any => {
1988
+ if (typeof item === "function") {
1989
+ return guardCallable(item, explicitName || item.name || "tool", mergedOpts);
1990
+ }
1991
+ if (item && typeof item === "object") {
1992
+ const name = String(explicitName || item.name || "tool");
1993
+ const wrappedObj: Record<string, unknown> = { ...item };
1994
+ for (const methodKey of ["execute", "invoke", "func", "call"]) {
1995
+ if (typeof item[methodKey] === "function") {
1996
+ const origFn = item[methodKey].bind(item);
1997
+ wrappedObj[methodKey] = guardCallable(origFn, name, mergedOpts);
1998
+ }
1999
+ }
2000
+ return wrappedObj;
2001
+ }
2002
+ return item;
2003
+ };
2004
+
2005
+ if (typeof tools === "function") {
2006
+ return wrapItem(tools) as T;
2007
+ }
2008
+ if (Array.isArray(tools)) {
2009
+ return tools.map((t) => wrapItem(t)) as unknown as T;
2010
+ }
2011
+ if (tools && typeof tools === "object") {
2012
+ const out: Record<string, unknown> = {};
2013
+ for (const [key, val] of Object.entries(tools as Record<string, unknown>)) {
2014
+ out[key] = wrapItem(val, key);
2015
+ }
2016
+ return out as T;
2017
+ }
2018
+ return tools;
2019
+ }
2020
+
1539
2021
  export default Memory;