@axiom-lattice/protocols 7.2.0 → 7.3.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@axiom-lattice/protocols",
3
- "version": "7.2.0",
3
+ "version": "7.3.0",
4
4
  "description": "Unified protocol type definitions for Axiom Lattice framework",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -11,7 +11,7 @@ import { BaseLatticeProtocol, LatticeMessage } from "./BaseLatticeProtocol";
11
11
  /**
12
12
  * MCP transport type
13
13
  */
14
- export type McpTransportType = "stdio" | "streamable_http" | "sse";
14
+ export type McpTransportType = "stdio" | "streamable_http";
15
15
 
16
16
  /**
17
17
  * MCP protocol era selection for client connections.
@@ -41,7 +41,7 @@ export interface McpServerConfig {
41
41
  /** Environment variables (stdio transport; credentials passed to the server process) */
42
42
  env?: Record<string, string>;
43
43
  /**
44
- * Custom HTTP headers sent with every request (streamable_http / sse only).
44
+ * Custom HTTP headers sent with every request (streamable_http only).
45
45
  * Commonly used for authentication, e.g. `{ Authorization: "Bearer <token>" }`.
46
46
  * Ignored for stdio transport. Values are encrypted at rest by config stores.
47
47
  */
@@ -21,6 +21,12 @@ export interface McpServerConfigEntry {
21
21
  */
22
22
  tenantId: string;
23
23
 
24
+ /**
25
+ * Personal assistant that owns this configuration, when it belongs to the
26
+ * personal data domain. Tenant-scoped entries leave this undefined.
27
+ */
28
+ ownerAssistantId?: string;
29
+
24
30
  /**
25
31
  * Business key for the configuration (unique within tenant)
26
32
  */
@@ -227,3 +233,115 @@ export interface McpServerConfigStore {
227
233
  */
228
234
  hasConfig(tenantId: string, id: string): Promise<boolean>;
229
235
  }
236
+
237
+ /**
238
+ * MCP server configuration owned by one personal assistant.
239
+ *
240
+ * Personal configs live in a separate store surface so tenant-only code paths
241
+ * can never read them by accident; the owning assistant id is part of every
242
+ * lookup key.
243
+ */
244
+ export interface PersonalMcpServerConfigEntry extends McpServerConfigEntry {
245
+ /** Personal assistant that owns this configuration. */
246
+ ownerAssistantId: string;
247
+ }
248
+
249
+ /**
250
+ * Store operations for the personal MCP data domain.
251
+ *
252
+ * Every method scopes by `(tenantId, ownerAssistantId)`. Implementations must
253
+ * never merge personal rows into the tenant-only methods of
254
+ * {@link McpServerConfigStore}.
255
+ */
256
+ export interface PersonalMcpServerConfigStore {
257
+ /** List all personal MCP configs belonging to one assistant. */
258
+ getAllConfigsForAssistant(
259
+ tenantId: string,
260
+ ownerAssistantId: string,
261
+ ): Promise<PersonalMcpServerConfigEntry[]>;
262
+
263
+ /**
264
+ * List every personal MCP config across tenants.
265
+ *
266
+ * Intended for operations and tests only; startup restoration must not call
267
+ * it (personal connections are established lazily).
268
+ */
269
+ getAllPersonalConfigsWithoutTenant(): Promise<PersonalMcpServerConfigEntry[]>;
270
+
271
+ /** Get one personal config by id, scoped to its assistant. */
272
+ getConfigByIdForAssistant(
273
+ tenantId: string,
274
+ ownerAssistantId: string,
275
+ id: string,
276
+ ): Promise<PersonalMcpServerConfigEntry | null>;
277
+
278
+ /** Get one personal config by business key, scoped to its assistant. */
279
+ getConfigByKeyForAssistant(
280
+ tenantId: string,
281
+ ownerAssistantId: string,
282
+ key: string,
283
+ ): Promise<PersonalMcpServerConfigEntry | null>;
284
+
285
+ /** Create a personal config for one assistant. */
286
+ createConfigForAssistant(
287
+ tenantId: string,
288
+ ownerAssistantId: string,
289
+ id: string,
290
+ data: CreateMcpServerConfigRequest,
291
+ ): Promise<PersonalMcpServerConfigEntry>;
292
+
293
+ /** Update a personal config by id, scoped to its assistant. */
294
+ updateConfigForAssistant(
295
+ tenantId: string,
296
+ ownerAssistantId: string,
297
+ id: string,
298
+ updates: Partial<UpdateMcpServerConfigRequest>,
299
+ ): Promise<PersonalMcpServerConfigEntry | null>;
300
+
301
+ /** Delete one personal config by id; returns whether a row was removed. */
302
+ deleteConfigForAssistant(
303
+ tenantId: string,
304
+ ownerAssistantId: string,
305
+ id: string,
306
+ ): Promise<boolean>;
307
+
308
+ /** Delete every personal config owned by one assistant; returns the count. */
309
+ deleteConfigsForAssistant(
310
+ tenantId: string,
311
+ ownerAssistantId: string,
312
+ ): Promise<number>;
313
+
314
+ /** Check whether a personal config id exists for one assistant. */
315
+ hasConfigForAssistant(
316
+ tenantId: string,
317
+ ownerAssistantId: string,
318
+ id: string,
319
+ ): Promise<boolean>;
320
+ }
321
+
322
+ /** A store that serves both the tenant and personal MCP data domains. */
323
+ export type McpConfigStoreWithPersonal =
324
+ McpServerConfigStore & PersonalMcpServerConfigStore;
325
+
326
+ /**
327
+ * Narrow a store to the personal MCP surface at runtime.
328
+ *
329
+ * Custom hosts may register a tenant-only MCP store; callers use this guard to
330
+ * degrade gracefully instead of assuming the personal methods exist.
331
+ */
332
+ export function isPersonalMcpServerConfigStore(
333
+ store: McpServerConfigStore,
334
+ ): store is McpConfigStoreWithPersonal {
335
+ const candidate = store as Partial<PersonalMcpServerConfigStore>;
336
+ return (
337
+ typeof candidate.getAllConfigsForAssistant === "function" &&
338
+ typeof candidate.getAllPersonalConfigsWithoutTenant === "function" &&
339
+ typeof candidate.getConfigByIdForAssistant === "function" &&
340
+ typeof candidate.getConfigByKeyForAssistant === "function" &&
341
+ typeof candidate.createConfigForAssistant === "function" &&
342
+ typeof candidate.updateConfigForAssistant === "function" &&
343
+ typeof candidate.deleteConfigForAssistant === "function" &&
344
+ typeof candidate.deleteConfigsForAssistant === "function" &&
345
+ typeof candidate.hasConfigForAssistant === "function"
346
+ );
347
+ }
@@ -8,6 +8,7 @@
8
8
  */
9
9
 
10
10
  import type { LLMConfig } from "./ModelLatticeProtocol";
11
+ import { PLATFORM_TENANT_ID } from "./PlatformOpsProtocol";
11
12
 
12
13
  /**
13
14
  * Wire protocol used to talk to the upstream provider.
@@ -65,6 +66,20 @@ export const DEFAULT_MODEL_KEY = "default";
65
66
  export const EMBEDDING_DEFAULT_KEY = "default:embedding";
66
67
  export const ASR_DEFAULT_KEY = "default:asr";
67
68
 
69
+ /**
70
+ * Reserved tenant id for the platform-owned model provider catalog.
71
+ *
72
+ * The platform catalog lives in the same encrypted `modelProvider` store as a
73
+ * tenant's own providers, under this reserved id. It is deliberately distinct
74
+ * from the deployment `"default"` namespace, which holds the models registered
75
+ * from environment configuration at boot.
76
+ *
77
+ * Resolution uses it as the second step: a tenant with providers of its own
78
+ * never reaches it, a tenant with none falls back to it while it has providers,
79
+ * and only an empty platform catalog falls through to the deployment namespace.
80
+ */
81
+ export const PLATFORM_MODEL_TENANT_ID = PLATFORM_TENANT_ID;
82
+
68
83
  /**
69
84
  * Build the tenant-scoped model key.
70
85
  *
@@ -445,11 +460,12 @@ export interface ModelSelection {
445
460
  */
446
461
  kind?: ModelKind;
447
462
  /**
448
- * Whether this is the tenant's default model.
463
+ * Whether this is the tenant's default model of its kind.
449
464
  *
450
- * At most one model per tenant may carry it. Omitted means "leave the stored
451
- * flag alone"; a default can only be replaced, never dropped by omission —
452
- * see `ModelProviderStore.getDefaultModel`.
465
+ * The flag is scoped per *(tenant, kind)*: at most one chat model, one
466
+ * embedding model, and one ASR model may carry it. Omitted means "leave the
467
+ * stored flag alone"; a default can only be replaced, never dropped by
468
+ * omission — see `ModelProviderStore.getDefaultModel`.
453
469
  */
454
470
  isDefault?: boolean;
455
471
  }
@@ -0,0 +1,80 @@
1
+ /** Actor on whose behalf a platform-level audit record was produced. */
2
+ export type PlatformAuditInitiator =
3
+ | { type: "human"; userId: string; role: "owner" | "admin" | "auditor" }
4
+ | { type: "bootstrap" }
5
+ | { type: "system"; component: string };
6
+
7
+ /** Execution surface that performed the audited platform operation. */
8
+ export type PlatformAuditExecutor =
9
+ | { type: "admin_center"; route: string }
10
+ | {
11
+ type: "ops_agent";
12
+ agentId: "platform-ops";
13
+ threadId: string;
14
+ runId: string;
15
+ toolName: string;
16
+ }
17
+ | { type: "bootstrap" }
18
+ | { type: "system"; component: string };
19
+
20
+ /** Entry point that originated a platform-level audit record. */
21
+ export type PlatformAuditSource =
22
+ | "admin_center"
23
+ | "ops_agent"
24
+ | "bootstrap"
25
+ | "system";
26
+
27
+ /** Kind of platform operation captured by an audit record. */
28
+ export type PlatformAuditAction = "write" | "playbook";
29
+
30
+ /** Terminal outcome of the audited operation. */
31
+ export type PlatformAuditStatus = "ok" | "error" | "cancelled";
32
+
33
+ /** Input accepted when appending a platform audit record. */
34
+ export interface PlatformAuditAppendInput {
35
+ initiator: PlatformAuditInitiator;
36
+ source: PlatformAuditSource;
37
+ executor: PlatformAuditExecutor;
38
+ tenantId?: string;
39
+ action: PlatformAuditAction;
40
+ status: PlatformAuditStatus;
41
+ summary: Record<string, unknown>;
42
+ before?: Record<string, unknown>;
43
+ after?: Record<string, unknown>;
44
+ errorCode?: string;
45
+ durationMs: number;
46
+ }
47
+
48
+ /** Persisted platform audit record. */
49
+ export interface PlatformAuditRecord extends PlatformAuditAppendInput {
50
+ id: string;
51
+ createdAt: Date;
52
+ }
53
+
54
+ /**
55
+ * Filter and pagination options for querying platform audit records.
56
+ *
57
+ * Results are ordered newest-first by `createdAt` descending, then by `id`
58
+ * descending as a total-order tie-break. `from` is inclusive and `to` is
59
+ * exclusive on `createdAt`. `limit` defaults to 100; negative `offset` and
60
+ * `limit` values are clamped to 0. `initiatorUserId` matches human initiators
61
+ * only.
62
+ */
63
+ export interface PlatformAuditQuery {
64
+ initiatorUserId?: string;
65
+ source?: PlatformAuditSource;
66
+ tenantId?: string;
67
+ action?: PlatformAuditAction;
68
+ status?: PlatformAuditStatus;
69
+ from?: string;
70
+ to?: string;
71
+ limit?: number;
72
+ offset?: number;
73
+ }
74
+
75
+ /** Persistence operations for platform audit records. */
76
+ export interface PlatformAuditStore {
77
+ append(record: PlatformAuditAppendInput): Promise<PlatformAuditRecord>;
78
+ get(id: string): Promise<PlatformAuditRecord | null>;
79
+ query(params: PlatformAuditQuery): Promise<PlatformAuditRecord[]>;
80
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * PlatformOpsProtocol
3
+ *
4
+ * Shared identity constants for the platform-scoped operations surface.
5
+ *
6
+ * The Ops Agent runs on a hidden system tenant so it can reuse the normal
7
+ * agent runtime (threads, runs, SSE, leases) without appearing in any tenant
8
+ * or agent list. These identifiers are deliberately reserved and must not be
9
+ * user-selectable.
10
+ */
11
+
12
+ /**
13
+ * Reserved tenant id that owns platform-scoped configuration and agent
14
+ * execution (platform model catalog, Ops Agent threads, …).
15
+ */
16
+ export const PLATFORM_TENANT_ID = "__platform__";
17
+
18
+ /**
19
+ * Fixed key of the platform operations agent. It is registered explicitly at
20
+ * startup rather than created through assistant management routes.
21
+ */
22
+ export const PLATFORM_OPS_AGENT_ID = "platform-ops";
23
+
24
+ /**
25
+ * Stable error code returned when a normal tenant route tries to mutate the
26
+ * hidden platform tenant.
27
+ */
28
+ export const PLATFORM_TENANT_PROTECTED_ERROR = "PLATFORM_TENANT_PROTECTED";
29
+
30
+ /**
31
+ * Whether a tenant id belongs to the hidden platform tenant.
32
+ */
33
+ export function isPlatformTenantId(tenantId: string): boolean {
34
+ return tenantId === PLATFORM_TENANT_ID;
35
+ }
36
+
37
+ /**
38
+ * Stable error raised when a tenant-plane operation tries to address the
39
+ * hidden platform tenant.
40
+ */
41
+ export class PlatformTenantProtectedError extends Error {
42
+ readonly code = PLATFORM_TENANT_PROTECTED_ERROR;
43
+
44
+ constructor(message = "The hidden platform tenant is protected") {
45
+ super(message);
46
+ this.name = "PlatformTenantProtectedError";
47
+ }
48
+ }
49
+
50
+ /**
51
+ * Rejects any attempt to create or mutate a link into the hidden platform
52
+ * tenant.
53
+ */
54
+ export function assertNotPlatformTenant(tenantId: string): void {
55
+ if (isPlatformTenantId(tenantId)) {
56
+ throw new PlatformTenantProtectedError();
57
+ }
58
+ }
59
+
60
+ /** Fixed workspace used by Platform Ops threads inside the hidden tenant. */
61
+ export const PLATFORM_OPS_WORKSPACE_ID = "platform-ops";
62
+
63
+ /** Fixed project used by Platform Ops threads inside the hidden tenant. */
64
+ export const PLATFORM_OPS_PROJECT_ID = "platform-ops";
65
+
66
+ /** High-risk Ops playbook discriminator executed by the playbook executor. */
67
+ export type PlatformOpsPlaybookKind =
68
+ | "transfer_owner"
69
+ | "offboard_member"
70
+ | "delete_tenant"
71
+ | "delete_oidc_provider"
72
+ | "rotate_oidc_provider"
73
+ | "reset_settings";
@@ -36,15 +36,23 @@ export interface ResolvedPlatformBranding {
36
36
  publicConsoleUrl?: string;
37
37
  }
38
38
 
39
+ /** Platform override for one gateway rate-limit policy. */
40
+ export interface PlatformRateLimitPolicyOverride {
41
+ /** New fixed-window request limit. Omitted keeps the deployment limit. */
42
+ limit?: number;
43
+ /** Set false to disable this policy. Omitted keeps the deployment state. */
44
+ enabled?: boolean;
45
+ }
46
+
39
47
  /** Persisted, partial platform settings document managed by platform admins. */
40
48
  export interface PlatformSettingsDocument {
41
49
  auth?: { emailCompletionEnabled?: boolean };
42
50
  invite?: { defaultExpiresInHours?: number; defaultMaxUses?: number };
43
51
  rateLimits?: {
44
- openApiPerMinute?: number;
45
- openAgentPerMinute?: number;
46
- a2aJsonRpcPerMinute?: number;
47
- a2aJsonRpcIpPerMinute?: number;
52
+ /** Per-policy platform overrides keyed by policy name. */
53
+ policies?: Record<string, PlatformRateLimitPolicyOverride>;
54
+ /** PATCH-only command: remove platform overrides for these policies. */
55
+ resetPolicies?: string[];
48
56
  maxActiveRunTasksPerTenant?: number | null;
49
57
  };
50
58
  branding?: PlatformBrandingSettings;
@@ -88,6 +96,8 @@ export interface PlatformSettingsProvider {
88
96
  getEffective(): EffectivePlatformSettings;
89
97
  getInviteDefaults(): EffectivePlatformSettings["invite"];
90
98
  getRateLimits(): EffectivePlatformSettings["rateLimits"];
99
+ /** Platform-only policy overrides; absent for consumers that do not need them. */
100
+ getRateLimitPolicyOverrides?(): Record<string, PlatformRateLimitPolicyOverride>;
91
101
  }
92
102
 
93
103
  /** Persistence operations for platform settings with version CAS. */
package/src/index.ts CHANGED
@@ -116,3 +116,5 @@ export * from "./OpenProtocol";
116
116
  export * from "./McpUiProtocol";
117
117
  export * from "./ObservabilityDashboardProtocol";
118
118
  export * from "./PlatformSettingsProtocol";
119
+ export * from "./PlatformAuditProtocol";
120
+ export * from "./PlatformOpsProtocol";