@minion-stack/shared 0.5.0 → 0.7.0

package/dist/gateway/cache-events.d.ts

@@ -0,0 +1,22 @@
+export type CacheInvalidateSource = 'hub' | 'gateway' | 'paperclip' | 'browser' | 'site';
+export interface CacheInvalidatePayload {
+    /** Tag names whose entries should be busted. Always present (may be empty if `keys` covers the bust). */
+    tags: string[];
+    /** Optional surgical key list — busted in addition to tag-matched keys. */
+    keys?: string[];
+    /** Runtime that originated the mutation. */
+    source: CacheInvalidateSource;
+    /** Per-process unique id so emitters can dedupe their own busts. */
+    sourceId: string;
+    /** Tenant scope — subscribers may gate on this. Empty string means global/no-tenant. */
+    tenantId: string;
+    /** Emission timestamp, ms since epoch. */
+    ts: number;
+}
+export interface CacheInvalidateEvent {
+    type: 'event';
+    event: 'cache.invalidate';
+    payload: CacheInvalidatePayload;
+}
+export declare function isCacheInvalidateEvent(value: unknown): value is CacheInvalidateEvent;
+//# sourceMappingURL=cache-events.d.ts.map

package/dist/gateway/cache-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-events.d.ts","sourceRoot":"","sources":["../../src/gateway/cache-events.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzF,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4CAA4C;IAC5C,MAAM,EAAE,qBAAqB,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAapF"}

package/dist/gateway/cache-events.js

@@ -0,0 +1,21 @@
+// Cache invalidation gateway event frame.
+//
+// Convention follows existing EventFrame in ./types.ts:
+//   { type: 'event', event: '<name>', payload: {...} }
+// (No `v: 3` discriminator — the gateway WS protocol does not version frames.)
+export function isCacheInvalidateEvent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v.type !== 'event' || v.event !== 'cache.invalidate')
+        return false;
+    if (typeof v.payload !== 'object' || v.payload === null)
+        return false;
+    const p = v.payload;
+    return (Array.isArray(p.tags) &&
+        typeof p.source === 'string' &&
+        typeof p.sourceId === 'string' &&
+        typeof p.tenantId === 'string' &&
+        typeof p.ts === 'number');
+}
+//# sourceMappingURL=cache-events.js.map

package/dist/gateway/cache-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-events.js","sourceRoot":"","sources":["../../src/gateway/cache-events.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,wDAAwD;AACxD,uDAAuD;AACvD,+EAA+E;AAyB/E,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAC;IACvE,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAkC,CAAC;IAC/C,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QACrB,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CACzB,CAAC;AACJ,CAAC"}

package/dist/gateway/cache-events.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache-events.test.d.ts.map

package/dist/gateway/cache-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-events.test.d.ts","sourceRoot":"","sources":["../../src/gateway/cache-events.test.ts"],"names":[],"mappings":""}

package/dist/gateway/cache-events.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { isCacheInvalidateEvent } from './cache-events.js';
+describe('CacheInvalidateEvent', () => {
+    it('isCacheInvalidateEvent returns true for a valid event', () => {
+        const evt = {
+            type: 'event',
+            event: 'cache.invalidate',
+            payload: {
+                tags: ['t:abc:agent-groups'],
+                keys: [],
+                source: 'hub',
+                sourceId: 'vercel-fn-1',
+                tenantId: 'ten_abc',
+                ts: 1715500000000,
+            },
+        };
+        expect(isCacheInvalidateEvent(evt)).toBe(true);
+    });
+    it('isCacheInvalidateEvent returns false for the wrong name', () => {
+        const evt = {
+            type: 'event',
+            event: 'chat.message',
+            payload: { tags: [], keys: [], source: 'hub', sourceId: 'x', tenantId: 't', ts: 0 },
+        };
+        expect(isCacheInvalidateEvent(evt)).toBe(false);
+    });
+    it('isCacheInvalidateEvent returns false for non-objects', () => {
+        expect(isCacheInvalidateEvent(null)).toBe(false);
+        expect(isCacheInvalidateEvent('event')).toBe(false);
+        expect(isCacheInvalidateEvent({})).toBe(false);
+    });
+    it('isCacheInvalidateEvent allows missing optional keys', () => {
+        const evt = {
+            type: 'event',
+            event: 'cache.invalidate',
+            payload: {
+                tags: ['t:abc'],
+                source: 'gateway',
+                sourceId: 'gw-1',
+                tenantId: 'ten_abc',
+                ts: 0,
+            },
+        };
+        expect(isCacheInvalidateEvent(evt)).toBe(true);
+    });
+});
+//# sourceMappingURL=cache-events.test.js.map

package/dist/gateway/cache-events.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-events.test.js","sourceRoot":"","sources":["../../src/gateway/cache-events.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAA6B,MAAM,mBAAmB,CAAC;AAEtF,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,GAAG,GAAyB;YAChC,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE;gBACP,IAAI,EAAE,CAAC,oBAAoB,CAAC;gBAC5B,IAAI,EAAE,EAAE;gBACR,MAAM,EAAE,KAAK;gBACb,QAAQ,EAAE,aAAa;gBACvB,QAAQ,EAAE,SAAS;gBACnB,EAAE,EAAE,aAAa;aAClB;SACF,CAAC;QACF,MAAM,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,GAAG,GAAG;YACV,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,cAAc;YACrB,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE;SACpF,CAAC;QACF,MAAM,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,MAAM,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,GAAG,GAAG;YACV,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE;gBACP,IAAI,EAAE,CAAC,OAAO,CAAC;gBACf,MAAM,EAAE,SAAS;gBACjB,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,SAAS;gBACnB,EAAE,EAAE,CAAC;aACN;SACF,CAAC;QACF,MAAM,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/gateway/index.d.ts

@@ -2,4 +2,7 @@ export * from './types.js';
 export * from './protocol.js';
 export * from './connection.js';
 export * from './client.js';
+export * from './cache-events.js';
+export * from './secrets.js';
+export * from './shells.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/gateway/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/gateway/index.js

@@ -2,4 +2,7 @@ export * from './types.js';
 export * from './protocol.js';
 export * from './connection.js';
 export * from './client.js';
+export * from './cache-events.js';
+export * from './secrets.js';
+export * from './shells.js';
 //# sourceMappingURL=index.js.map

package/dist/gateway/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/gateway/secrets.d.ts

@@ -0,0 +1,85 @@
+export declare const SECRETS_METHODS: {
+    readonly list: "secrets.list";
+    readonly set: "secrets.set";
+    readonly clear: "secrets.clear";
+    readonly probe: "secrets.probe";
+    readonly setScoped: "secrets.set_scoped";
+    readonly clearScoped: "secrets.clear_scoped";
+    readonly probeScoped: "secrets.probe_scoped";
+};
+export type SecretsProbeStatus = "ok" | "invalid" | "unknown" | "missing";
+export type SecretsKind = "static" | "dynamic";
+/** One entry in the secrets.list response payload. NEVER contains plaintext. */
+export interface SecretsSummary {
+    rowKey: string;
+    groupKey: string;
+    instanceId: string | null;
+    kind: SecretsKind;
+    ownerPlugin: string;
+    label: string;
+    description?: string;
+    probe: string;
+    configured: boolean;
+    probeStatus: SecretsProbeStatus;
+    probeMessage: string | null;
+    lastProbeAt: number | null;
+    updatedAt: number;
+}
+export interface SecretsListParams {
+}
+export interface SecretsListResult {
+    secrets: SecretsSummary[];
+}
+export interface SecretsSetParams {
+    key: string;
+    value: string;
+}
+export interface SecretsSetResult {
+    key: string;
+    probeStatus: SecretsProbeStatus;
+    probeMessage: string;
+}
+export interface SecretsClearParams {
+    key: string;
+}
+export interface SecretsClearResult {
+    key: string;
+}
+export interface SecretsProbeParams {
+    key: string;
+}
+export interface SecretsProbeResult {
+    key: string;
+    probeStatus: SecretsProbeStatus;
+    probeMessage: string;
+}
+export interface SecretsSetScopedParams {
+    groupKey: string;
+    instanceId: string;
+    value: string;
+}
+export interface SecretsSetScopedResult {
+    groupKey: string;
+    instanceId: string;
+    probeStatus: SecretsProbeStatus;
+    probeMessage: string;
+}
+export interface SecretsClearScopedParams {
+    groupKey: string;
+    instanceId: string;
+}
+export interface SecretsClearScopedResult {
+    groupKey: string;
+    instanceId: string;
+}
+export interface SecretsProbeScopedParams {
+    groupKey: string;
+    instanceId: string;
+}
+export interface SecretsProbeScopedResult {
+    groupKey: string;
+    instanceId: string;
+    probeStatus: SecretsProbeStatus;
+    probeMessage: string;
+}
+//# sourceMappingURL=secrets.d.ts.map

package/dist/gateway/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/gateway/secrets.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/C,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,kBAAkB,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,iBAAiB;CAEjC;AACD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAGD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,kBAAkB,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,kBAAkB,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,kBAAkB,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,kBAAkB,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/gateway/secrets.js

@@ -0,0 +1,11 @@
+// RPC method name constants (use these on both client and server)
+export const SECRETS_METHODS = {
+    list: "secrets.list",
+    set: "secrets.set",
+    clear: "secrets.clear",
+    probe: "secrets.probe",
+    setScoped: "secrets.set_scoped",
+    clearScoped: "secrets.clear_scoped",
+    probeScoped: "secrets.probe_scoped",
+};
+//# sourceMappingURL=secrets.js.map

package/dist/gateway/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../src/gateway/secrets.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,cAAc;IACpB,GAAG,EAAE,aAAa;IAClB,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,eAAe;IACtB,SAAS,EAAE,oBAAoB;IAC/B,WAAW,EAAE,sBAAsB;IACnC,WAAW,EAAE,sBAAsB;CAC3B,CAAC"}

package/dist/gateway/shells.d.ts

@@ -0,0 +1,346 @@
+export declare const SHELLS_METHODS: {
+    readonly list: "shells.list";
+    readonly get: "shells.get";
+    readonly quota: "shells.quota";
+    readonly provision: "shells.provision";
+    readonly invoke: "shells.invoke";
+    readonly cancel: "shells.cancel";
+    readonly archive: "shells.archive";
+    readonly wake: "shells.wake";
+    readonly restart: "shells.restart";
+    readonly destroy: "shells.destroy";
+    readonly backupNow: "shells.backup_now";
+    readonly listBackups: "shells.list_backups";
+    readonly update: "shells.update";
+    readonly register: "shells.register";
+    readonly heartbeat: "shells.heartbeat";
+    readonly fatal: "shells.fatal";
+};
+export declare const SHELLS_EVENTS: {
+    readonly online: "shell.online";
+    readonly archived: "shell.archived";
+    readonly errored: "shell.error";
+    readonly delta: "shell.delta";
+    readonly final: "shell.final";
+    readonly backupDone: "shell.backup_done";
+    readonly quotaChanged: "shells.quota_changed";
+};
+/** Identifier of a harness baked into an exe.dev image. */
+export type ShellHarness = 'hermes' | 'claude-code' | 'codex' | (string & {});
+/** Lifecycle state. */
+export type ShellStatus = 'provisioning' | 'online' | 'archived' | 'error';
+/** Reason qualifier accompanying status="error". */
+export type ShellErrorReason = 'provision_failed' | 'bridge_unreachable' | 'backup_stuck' | 'restore_failed' | 'exedev_outage' | 'unknown';
+/** Backup cadence. `manual` means no automatic backups; user triggers via shells.backup_now. */
+export type ShellBackupCadence = 'hourly' | 'daily' | 'weekly' | 'manual';
+/** One shell row as returned by shells.list / shells.get. Never contains secrets. */
+export interface ShellSummary {
+    shellId: string;
+    vmName: string;
+    displayName: string;
+    harness: ShellHarness;
+    image: string;
+    region: string;
+    status: ShellStatus;
+    errorReason?: ShellErrorReason;
+    errorMessage?: string;
+    diskGB: number;
+    memoryMB: number;
+    /** Null = always-on (auto-archive disabled). */
+    archiveIdleMs: number | null;
+    backupCadence: ShellBackupCadence;
+    backupTarget: string;
+    lastInvokeAt: number | null;
+    lastBackupAt: number | null;
+    lastBackupBytes: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Quota snapshot returned by shells.quota. */
+export interface ShellsQuota {
+    shells: {
+        used: number;
+        limit: number;
+    };
+    diskGB: {
+        used: number;
+        limit: number;
+    };
+    memoryMB: {
+        used: number;
+        limit: number;
+    };
+    shelleyUSD: {
+        used: number;
+        limit: number;
+    };
+    egressGB: {
+        used: number;
+        limit: number;
+    };
+    /** Soft headroom — used by the provisioner to refuse new shells before the hard cap. */
+    headroom: {
+        diskGB: number;
+    };
+}
+/** shells.list — no params. Returns ShellSummary[]. */
+export interface ShellsListResponse {
+    shells: ShellSummary[];
+}
+/** shells.get */
+export interface ShellsGetParams {
+    shellId: string;
+}
+export type ShellsGetResponse = ShellSummary;
+/** shells.quota — no params. */
+export type ShellsQuotaResponse = ShellsQuota;
+/** shells.provision */
+export interface ShellsProvisionParams {
+    displayName: string;
+    harness: ShellHarness;
+    image?: string;
+    region?: string;
+    diskGB?: number;
+    memoryMB?: number;
+    archiveIdleMs?: number | null;
+    backupCadence?: ShellBackupCadence;
+    /** Optional initial prompt forwarded to the harness on first boot. */
+    initialPrompt?: string;
+}
+export interface ShellsProvisionResponse {
+    shellId: string;
+    vmName: string;
+    status: ShellStatus;
+    deviceToken: string;
+}
+/** shells.invoke — forwards to the bridge, which translates to ACP `session/prompt`. */
+export interface ShellsInvokeParams {
+    shellId: string;
+    sessionId: string;
+    input: {
+        kind: 'text';
+        text: string;
+    } | {
+        kind: 'multimodal';
+        parts: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+    };
+    /** Force-wake if archived. Default true. */
+    wakeIfArchived?: boolean;
+}
+export interface ShellsInvokeResponse {
+    runId: string;
+    startedAt: number;
+}
+/** shells.cancel — forwards to ACP `session/cancel`. */
+export interface ShellsCancelParams {
+    shellId: string;
+    runId: string;
+}
+export interface ShellsCancelResponse {
+    cancelled: boolean;
+}
+/** shells.archive — backup + ssh exe.dev rm. Idempotent on already-archived. */
+export interface ShellsArchiveParams {
+    shellId: string;
+    /** If true, skip backup (data-loss). Default false. */
+    skipBackup?: boolean;
+}
+export interface ShellsArchiveResponse {
+    shellId: string;
+    status: ShellStatus;
+    backupId?: string;
+    backupBytes?: number;
+}
+/** shells.wake — provision fresh VM + restore from latest backup. */
+export interface ShellsWakeParams {
+    shellId: string;
+    /** Backup to restore from. Default: latest. */
+    backupId?: string;
+}
+export interface ShellsWakeResponse {
+    shellId: string;
+    status: ShellStatus;
+    restoringFromBackupId: string;
+}
+/** shells.restart — `ssh exe.dev restart`. Online shells only. */
+export interface ShellsRestartParams {
+    shellId: string;
+}
+export interface ShellsRestartResponse {
+    shellId: string;
+    status: ShellStatus;
+}
+/** shells.destroy — permanent. `ssh exe.dev rm` + drop B2 backups (opt-out). */
+export interface ShellsDestroyParams {
+    shellId: string;
+    keepBackups?: boolean;
+}
+export interface ShellsDestroyResponse {
+    shellId: string;
+    removedBackups: number;
+}
+/** shells.backup_now — manual backup trigger. Returns when upload completes. */
+export interface ShellsBackupNowParams {
+    shellId: string;
+}
+export interface ShellsBackupNowResponse {
+    backupId: string;
+    bytes: number;
+    uploadMs: number;
+}
+/** shells.list_backups */
+export interface ShellsListBackupsParams {
+    shellId: string;
+    limit?: number;
+}
+export interface ShellBackupEntry {
+    backupId: string;
+    shellId: string;
+    bytes: number;
+    createdAt: number;
+    restoredAt: number | null;
+}
+export interface ShellsListBackupsResponse {
+    backups: ShellBackupEntry[];
+}
+/** shells.update — partial. Server validates which fields are mutable per status. */
+export interface ShellsUpdateParams {
+    shellId: string;
+    patch: Partial<Pick<ShellSummary, 'displayName' | 'archiveIdleMs' | 'backupCadence' | 'backupTarget'>>;
+}
+export type ShellsUpdateResponse = ShellSummary;
+/** shells.register — bridge claims its shellId after connecting. */
+export interface ShellsRegisterParams {
+    shellId: string;
+    deviceToken: string;
+    harness: ShellHarness;
+    harnessVersion: string;
+    bridgeVersion: string;
+    capabilities: ShellCapabilities;
+}
+export interface ShellCapabilities {
+    /** ACP methods this harness supports. Gateway uses to reject unsupported invokes early. */
+    acpMethods: string[];
+    /** True if the harness can stream `session/update` events. */
+    streaming: boolean;
+    /** Backup mechanism the bridge uses ('tar+b2', 'rclone', …). */
+    backupKind: string;
+    /** Max concurrent runs supported (1 for single-threaded harnesses). */
+    maxConcurrentRuns: number;
+}
+export interface ShellsRegisterResponse {
+    shellId: string;
+    /** Server-issued heartbeat cadence (ms). Bridge calls shells.heartbeat every N ms. */
+    heartbeatMs: number;
+}
+/** shells.heartbeat — bridge liveness ping. */
+export interface ShellsHeartbeatParams {
+    shellId: string;
+    activeRunIds: string[];
+    diskUsedMB: number;
+    memoryUsedMB: number;
+}
+export type ShellsHeartbeatResponse = {
+    ts: number;
+};
+/** shells.fatal — bridge reports unrecoverable error before exiting. */
+export interface ShellsFatalParams {
+    shellId: string;
+    reason: ShellErrorReason;
+    message: string;
+}
+export type ShellsFatalResponse = {
+    acknowledged: true;
+};
+/** shell.online — emitted when bridge registers (after provision OR after wake). */
+export interface ShellOnlinePayload {
+    shellId: string;
+    harness: ShellHarness;
+    harnessVersion: string;
+    /** True if this transition was from 'archived' rather than 'provisioning'. */
+    resumedFromArchive: boolean;
+}
+/** shell.archived — emitted when archive completes successfully. */
+export interface ShellArchivedPayload {
+    shellId: string;
+    backupId: string;
+    backupBytes: number;
+}
+/** shell.error — emitted on any transition into status='error'. */
+export interface ShellErrorPayload {
+    shellId: string;
+    reason: ShellErrorReason;
+    message: string;
+    /** Suggested next user action: 'restart' | 'wake' | 'destroy' | 'wait' | null. */
+    remediation: 'restart' | 'wake' | 'destroy' | 'wait' | null;
+}
+/**
+ * shell.delta — streaming partial output from the harness.
+ * Mirrors ChatEvent shape so existing hub stream renderers can consume it
+ * with minimal adaptation.
+ */
+export interface ShellDeltaPayload {
+    shellId: string;
+    runId: string;
+    sessionId: string;
+    seq: number;
+    /** Raw ACP `session/update` payload, passed through. */
+    acpUpdate: unknown;
+}
+/** shell.final — emitted once per runId on completion (success, abort, or harness error). */
+export interface ShellFinalPayload {
+    shellId: string;
+    runId: string;
+    sessionId: string;
+    state: 'final' | 'aborted' | 'error';
+    stopReason?: string;
+    errorMessage?: string;
+    /** Total wall time in ms from invoke to final. */
+    durationMs: number;
+    /** Optional usage stats reported by the harness (token counts, etc.). */
+    usage?: unknown;
+}
+/** shell.backup_done — emitted when a backup (scheduled or manual) completes. */
+export interface ShellBackupDonePayload {
+    shellId: string;
+    backupId: string;
+    bytes: number;
+    uploadMs: number;
+    trigger: 'scheduled' | 'manual' | 'pre_archive';
+}
+/** shells.quota_changed — emitted when any quota dimension crosses a threshold. */
+export interface ShellsQuotaChangedPayload {
+    quota: ShellsQuota;
+    /** Dimensions that crossed their amber/red threshold in this update. */
+    alerted: Array<'shells' | 'diskGB' | 'memoryMB' | 'shelleyUSD' | 'egressGB'>;
+}
+export declare function isShellEvent(frame: {
+    type?: unknown;
+    event?: unknown;
+}): frame is {
+    type: 'event';
+    event: string;
+    payload?: unknown;
+};
+export declare function isShellDelta(frame: {
+    type?: unknown;
+    event?: unknown;
+    payload?: unknown;
+}): frame is {
+    type: 'event';
+    event: typeof SHELLS_EVENTS.delta;
+    payload: ShellDeltaPayload;
+};
+export declare function isShellFinal(frame: {
+    type?: unknown;
+    event?: unknown;
+    payload?: unknown;
+}): frame is {
+    type: 'event';
+    event: typeof SHELLS_EVENTS.final;
+    payload: ShellFinalPayload;
+};
+//# sourceMappingURL=shells.d.ts.map

package/dist/gateway/shells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shells.d.ts","sourceRoot":"","sources":["../../src/gateway/shells.ts"],"names":[],"mappings":"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"}

package/dist/gateway/shells.js

@@ -0,0 +1,65 @@
+// Shells protocol — golden agents on exe.dev VMs.
+//
+// Spec: specs/2026-05-20-shells-golden-agents.md
+//
+// Wire shape follows the existing gateway frame protocol:
+//   - RPC : RequestFrame { type:'req',  id, method:'shells.*', params } ⇄ ResponseFrame
+//   - Event: EventFrame  { type:'event', event:'shell.*', payload }
+//
+// Two callers exist:
+//   1. Hub / channel clients invoke the gateway as usual (shells.list, shells.provision,
+//      shells.invoke, shells.archive, …)
+//   2. The in-VM `shells-bridge` process dials the gateway with a per-shell deviceToken,
+//      then calls shells.register to bind its WS connection to its shellId. Subsequent
+//      shells.invoke from other callers is forwarded by the gateway over this same
+//      connection.
+// =============================================================================
+// RPC method names — use these constants on both client and server.
+// =============================================================================
+export const SHELLS_METHODS = {
+    // Caller-side (hub / channel → gateway)
+    list: 'shells.list',
+    get: 'shells.get',
+    quota: 'shells.quota',
+    provision: 'shells.provision',
+    invoke: 'shells.invoke',
+    cancel: 'shells.cancel',
+    archive: 'shells.archive',
+    wake: 'shells.wake',
+    restart: 'shells.restart',
+    destroy: 'shells.destroy',
+    backupNow: 'shells.backup_now',
+    listBackups: 'shells.list_backups',
+    update: 'shells.update', // mutate name / archiveIdleMs / backupCadence / etc.
+    // Bridge-side (in-VM bridge → gateway)
+    register: 'shells.register',
+    heartbeat: 'shells.heartbeat',
+    fatal: 'shells.fatal',
+};
+// =============================================================================
+// Event names emitted by the gateway.
+// =============================================================================
+export const SHELLS_EVENTS = {
+    online: 'shell.online',
+    archived: 'shell.archived',
+    errored: 'shell.error',
+    delta: 'shell.delta',
+    final: 'shell.final',
+    backupDone: 'shell.backup_done',
+    quotaChanged: 'shells.quota_changed',
+};
+// =============================================================================
+// Type guards — convenience for hub stream handlers.
+// =============================================================================
+export function isShellEvent(frame) {
+    return (frame.type === 'event' &&
+        typeof frame.event === 'string' &&
+        (frame.event.startsWith('shell.') || frame.event.startsWith('shells.')));
+}
+export function isShellDelta(frame) {
+    return frame.type === 'event' && frame.event === SHELLS_EVENTS.delta;
+}
+export function isShellFinal(frame) {
+    return frame.type === 'event' && frame.event === SHELLS_EVENTS.final;
+}
+//# sourceMappingURL=shells.js.map

package/dist/gateway/shells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shells.js","sourceRoot":"","sources":["../../src/gateway/shells.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,0DAA0D;AAC1D,wFAAwF;AACxF,oEAAoE;AACpE,EAAE;AACF,qBAAqB;AACrB,yFAAyF;AACzF,yCAAyC;AACzC,yFAAyF;AACzF,uFAAuF;AACvF,mFAAmF;AACnF,mBAAmB;AAEnB,gFAAgF;AAChF,oEAAoE;AACpE,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,wCAAwC;IACxC,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,YAAY;IACjB,KAAK,EAAE,cAAc;IACrB,SAAS,EAAE,kBAAkB;IAC7B,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,eAAe;IACvB,OAAO,EAAE,gBAAgB;IACzB,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,gBAAgB;IACzB,OAAO,EAAE,gBAAgB;IACzB,SAAS,EAAE,mBAAmB;IAC9B,WAAW,EAAE,qBAAqB;IAClC,MAAM,EAAE,eAAe,EAAE,qDAAqD;IAE9E,uCAAuC;IACvC,QAAQ,EAAE,iBAAiB;IAC3B,SAAS,EAAE,kBAAkB;IAC7B,KAAK,EAAE,cAAc;CACb,CAAC;AAEX,gFAAgF;AAChF,sCAAsC;AACtC,gFAAgF;AAChF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM,EAAE,cAAc;IACtB,QAAQ,EAAE,gBAAgB;IAC1B,OAAO,EAAE,aAAa;IACtB,KAAK,EAAE,aAAa;IACpB,KAAK,EAAE,aAAa;IACpB,UAAU,EAAE,mBAAmB;IAC/B,YAAY,EAAE,sBAAsB;CAC5B,CAAC;AAsUX,gFAAgF;AAChF,qDAAqD;AACrD,gFAAgF;AAEhF,MAAM,UAAU,YAAY,CAC1B,KAA0C;IAE1C,OAAO,CACL,KAAK,CAAC,IAAI,KAAK,OAAO;QACtB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAA6D;IAE7D,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,CAAC,KAAK,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAA6D;IAE7D,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,CAAC,KAAK,CAAC;AACvE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minion-stack/shared",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared gateway protocol types and utilities for the Minion platform.",
   "license": "MIT",
   "repository": {
@@ -46,10 +46,10 @@
   ],
   "devDependencies": {
     "@types/ws": "^8.18.1",
-    "oxlint": ">=0.15.0",
+    "oxlint": "^1.66.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.9",
-    "ws": "^8.19.0",
+    "ws": "^8.21.0",
     "@minion-stack/tsconfig": "0.1.0"
   },
   "scripts": {