@skrr-ai/cli 0.1.22 → 0.1.23

package/dist/lib/managed-agent-keys.d.ts

@@ -0,0 +1,104 @@
+/**
+ * managed-agent-keys.ts — request client for `/api/admin/mgmt-keys`.
+ *
+ * ## Why this file exists
+ *
+ * The Managed Agents API (`/api/v1/*` — environments, agent releases, sessions,
+ * events, vaults) authenticates with an `osk_<live|test>_<secret>` key, and the
+ * only route that mints one is `POST /api/admin/mgmt-keys`. Nothing in the CLI
+ * reached it: a search of every command directory found no reference to
+ * `mgmt-keys` or `/api/v1` at all.
+ *
+ * So a headless operator, or a coding agent running locally, could be told by
+ * `/v1` that its credential was missing and had no command to mint one. The
+ * documented path was the dashboard, which a machine cannot open. That gap was
+ * recorded as the secondary half of OSK-7932, whose primary half was that the
+ * server-side pepper had never been configured in any environment — the API
+ * could not issue a key, and there was also no way to ask it to.
+ *
+ * ## Not the same thing as `skrr token`
+ *
+ * `skrr token` / `skrr create-token` mint a long-lived CLI token for
+ * bootstrapping a daemon on a headless machine — that is this CLI's own auth.
+ * These are API keys for a different surface, held by a Space, and presented by
+ * whatever calls `/api/v1`. The CLI already keeps `balance` and
+ * `payments wallet` apart for the same reason: two things called "credit" that
+ * are unrelated, where reading one for the other tells you something false.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings. A helper that assembles the URL is opaque to it, so the endpoint
+ * would read as unreachable and get allow-listed — a check going green on an
+ * assertion it never made.
+ */
+/**
+ * A key as the API returns it, in the API's OWN field names.
+ *
+ * snake_case, and mirrored rather than translated. `toPublic` in
+ * `routes/adminMgmtKeys.js` is the contract; a camelCase interface here would
+ * silently produce `undefined` for every field, which is precisely what the
+ * first version of this file did — it invented `createdAt`/`revokedAt` and an
+ * `env` that does not exist, and the list command printed nothing while the API
+ * was returning rows.
+ *
+ * There is no `env` field. The environment is encoded in `prefix`
+ * (`osk_live_…` / `osk_test_…`), which is also all a listing ever reveals of a
+ * secret.
+ */
+export interface ManagedAgentKey {
+    id: string;
+    name: string;
+    prefix?: string;
+    last_four?: string;
+    scopes: string[];
+    space_id?: string;
+    created_at?: string;
+    last_used_at?: string | null;
+    revoked_at?: string | null;
+    expires_at?: string | null;
+    rate_limit_override?: unknown;
+}
+/**
+ * The mint response: the public projection, FLAT, plus the secret.
+ *
+ * `secret` is returned exactly once — there is no endpoint that reveals it
+ * again — so a caller that discards this field has lost the credential and must
+ * rotate. The command layer says so where the value is printed rather than in a
+ * footnote.
+ */
+export type ManagedAgentKeyMint = ManagedAgentKey & {
+    secret: string;
+    secret_warning?: string;
+    /** Present on a rotate: the id of the key this one replaces. */
+    rotated_from?: string;
+};
+export interface CreateManagedAgentKeyInput {
+    spaceId: string;
+    name: string;
+    env?: 'live' | 'test';
+    scopes?: string[];
+    /** ISO 8601. The route refuses a value in the past. */
+    expiresAt?: string;
+}
+/**
+ * Mint a key for a Space.
+ *
+ * Space-owner only, enforced server-side — a member cannot mint against a Space
+ * they do not own, and the CLI does not pre-check that: a client-side guess at
+ * an authorization answer is one more place for the two to disagree.
+ */
+export declare function createManagedAgentKey(input: CreateManagedAgentKeyInput): Promise<ManagedAgentKeyMint>;
+/** Every key on a Space. Revoked rows are included, with `revokedAt` set. */
+export declare function listManagedAgentKeys(spaceId: string): Promise<ManagedAgentKey[]>;
+/** Revoke a key. Irreversible — a revoked key is never re-enabled, only replaced. */
+export declare function revokeManagedAgentKey(id: string, spaceId: string): Promise<{
+    id?: string;
+    revoked?: boolean;
+}>;
+/**
+ * Rotate a key: mint a replacement secret for the same row.
+ *
+ * Returns a secret under the same once-only rule as `create`.
+ */
+export declare function rotateManagedAgentKey(id: string, spaceId: string): Promise<ManagedAgentKeyMint>;

package/dist/lib/managed-agent-keys.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createManagedAgentKey = createManagedAgentKey;
+exports.listManagedAgentKeys = listManagedAgentKeys;
+exports.revokeManagedAgentKey = revokeManagedAgentKey;
+exports.rotateManagedAgentKey = rotateManagedAgentKey;
+const api_fetch_1 = require("./api-fetch");
+/**
+ * Mint a key for a Space.
+ *
+ * Space-owner only, enforced server-side — a member cannot mint against a Space
+ * they do not own, and the CLI does not pre-check that: a client-side guess at
+ * an authorization answer is one more place for the two to disagree.
+ */
+async function createManagedAgentKey(input) {
+    return (0, api_fetch_1.apiFetch)('/api/admin/mgmt-keys', {
+        method: 'POST',
+        body: {
+            space_id: input.spaceId,
+            name: input.name,
+            ...(input.env ? { env: input.env } : {}),
+            ...(input.scopes ? { scopes: input.scopes } : {}),
+            ...(input.expiresAt ? { expires_at: input.expiresAt } : {}),
+        },
+    });
+}
+/** Every key on a Space. Revoked rows are included, with `revokedAt` set. */
+async function listManagedAgentKeys(spaceId) {
+    // `{ data: [...] }` — the route's envelope. Guessed as `{ keys }` first, which
+    // returned an empty list against a space that had a key, and reported "No API
+    // keys on this space." That is the failure shape worth noting: a wrong
+    // envelope does not error, it reports absence.
+    const res = await (0, api_fetch_1.apiFetch)(`/api/admin/mgmt-keys?space_id=${encodeURIComponent(spaceId)}`);
+    return res?.data || [];
+}
+/** Revoke a key. Irreversible — a revoked key is never re-enabled, only replaced. */
+async function revokeManagedAgentKey(id, spaceId) {
+    return (0, api_fetch_1.apiFetch)(`/api/admin/mgmt-keys/${encodeURIComponent(id)}?space_id=${encodeURIComponent(spaceId)}`, { method: 'DELETE' });
+}
+/**
+ * Rotate a key: mint a replacement secret for the same row.
+ *
+ * Returns a secret under the same once-only rule as `create`.
+ */
+async function rotateManagedAgentKey(id, spaceId) {
+    return (0, api_fetch_1.apiFetch)(`/api/admin/mgmt-keys/${encodeURIComponent(id)}/rotate`, {
+        method: 'POST',
+        body: { space_id: spaceId },
+    });
+}

package/dist/lib/memory-scope.d.ts

@@ -1,13 +1,13 @@
 import type { MemoryScope } from '@skrr-ai/data-provider';
 /**
- * Shared `--agent` / `--tier` / `--workspace` flags for the memory commands.
+ * Shared `--agent` / `--tier` / `--pool-workspace` flags for compatibility Memory commands.
  *
  * A memory record lives in exactly one pool. These flags select which:
  *   - (default)              owner pool          → /api/memories
  *   - --agent <id>           a specific agent    → /api/agents/:id/memories
  *   - --tier user            cross-agent user    → /api/users/me/memories
  *   - --tier workspace       a workspace pool    → /api/workspaces/:id/memories
- *                            (requires --workspace <id>)
+ *                            (requires --pool-workspace <id>)
  *
  * Spread into a command's `flags` alongside its own. Resolve with
  * `resolveMemoryScope(flags)` into the `MemoryScope` the data-service accepts.
@@ -15,11 +15,12 @@ import type { MemoryScope } from '@skrr-ai/data-provider';
 export declare const memoryScopeFlags: {
     agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     tier: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-    workspace: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'pool-workspace': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
 };
 export interface MemoryScopeFlagValues {
     agent?: string;
     tier?: string;
+    'pool-workspace'?: string;
     workspace?: string;
 }
 /**

package/dist/lib/memory-scope.js

@@ -6,14 +6,14 @@ exports.resolveMemoryScopeOrFail = resolveMemoryScopeOrFail;
 exports.describeMemoryScope = describeMemoryScope;
 const core_1 = require("@oclif/core");
 /**
- * Shared `--agent` / `--tier` / `--workspace` flags for the memory commands.
+ * Shared `--agent` / `--tier` / `--pool-workspace` flags for compatibility Memory commands.
  *
  * A memory record lives in exactly one pool. These flags select which:
  *   - (default)              owner pool          → /api/memories
  *   - --agent <id>           a specific agent    → /api/agents/:id/memories
  *   - --tier user            cross-agent user    → /api/users/me/memories
  *   - --tier workspace       a workspace pool    → /api/workspaces/:id/memories
- *                            (requires --workspace <id>)
+ *                            (requires --pool-workspace <id>)
  *
  * Spread into a command's `flags` alongside its own. Resolve with
  * `resolveMemoryScope(flags)` into the `MemoryScope` the data-service accepts.
@@ -26,8 +26,8 @@ exports.memoryScopeFlags = {
         description: 'Memory pool tier to target (default: owner)',
         options: ['owner', 'user', 'workspace'],
     }),
-    workspace: core_1.Flags.string({
-        description: 'Workspace id (required when --tier workspace)',
+    'pool-workspace': core_1.Flags.string({
+        description: 'Compatibility Memory pool workspace id (required with --tier workspace; distinct from global --workspace request context)',
     }),
 };
 /**
@@ -40,14 +40,14 @@ function resolveMemoryScope(flags) {
     if (flags.agent && tier !== 'owner') {
         throw new Error('--agent cannot be combined with --tier user|workspace.');
     }
-    if (flags.workspace && tier !== 'workspace') {
-        throw new Error('--workspace is only valid with --tier workspace.');
+    if (flags['pool-workspace'] && tier !== 'workspace') {
+        throw new Error('--pool-workspace is only valid with --tier workspace.');
     }
     if (tier === 'workspace') {
-        if (!flags.workspace) {
-            throw new Error('--workspace <id> is required when --tier workspace.');
+        if (!flags['pool-workspace']) {
+            throw new Error('--pool-workspace <id> is required when --tier workspace. Global --workspace selects request context and cannot select a Memory pool.');
         }
-        return { tier: 'workspace', workspaceId: flags.workspace };
+        return { tier: 'workspace', workspaceId: flags['pool-workspace'] };
     }
     if (tier === 'user') {
         return { tier: 'user' };

package/dist/lib/memory-sync.d.ts

@@ -0,0 +1,114 @@
+export declare const MEMORY_SYNC_MANIFEST = ".memory-sync";
+export declare const MEMORY_SYNC_BASIS = ".memory-sync-basis";
+export declare const MEMORY_SYNC_CONFLICTS = ".memory-conflicts";
+export declare const MEMORY_SYNC_TOMBSTONES = ".memory-tombstones";
+export interface RemoteMemoryEntry {
+    memoryId: string;
+    path: string;
+    versionId: string;
+    revision: number;
+    contentHash: string | null;
+    document: string;
+}
+export interface MemorySyncSnapshot {
+    contractVersion: 1;
+    storeId: string;
+    owner: {
+        kind: 'agent' | 'space';
+        id: string;
+    };
+    access: 'read_only' | 'read_write';
+    authorizationGeneration: number;
+    cursor: string;
+    storeRevision: number;
+    index: string;
+    entries: RemoteMemoryEntry[];
+}
+export interface MemorySyncManifest {
+    contractVersion: 1;
+    storeId: string;
+    ownerUri: string;
+    access: 'read_only' | 'read_write' | 'revoked';
+    authorizationGeneration: number;
+    cursor: string;
+    updatedAt: string;
+}
+export interface MemorySyncChange {
+    cursor: string;
+    storeId: string;
+    memoryId?: string;
+    operation: 'upsert' | 'remove' | 'redact' | 'scope_reset';
+    authorizationGeneration: number;
+}
+export interface MemorySyncChanges {
+    contractVersion: 1;
+    storeId: string;
+    authorizationGeneration: number;
+    storeRevision?: number;
+    after: string;
+    cursor: string;
+    hasMore?: boolean;
+    index?: string;
+    resetRequired?: boolean;
+    reason?: string;
+    entries?: Array<{
+        change: MemorySyncChange;
+        head?: RemoteMemoryEntry | null;
+    }>;
+}
+export interface LocalMutation {
+    operation: 'encode' | 'reconsolidate' | 'delete';
+    input: Record<string, unknown>;
+    file: string;
+}
+export declare function fileForMemoryPath(memoryPath: string): string;
+export declare function readMaterializationBinding(rootInput: string): Promise<{
+    manifest: MemorySyncManifest | null;
+    cursor: string | null;
+}>;
+export declare function assertMaterializationSpaceContext(manifest: MemorySyncManifest | null, spaceId?: string): void;
+export declare function assertMaterializationStore(manifest: MemorySyncManifest | null, storeId: string): void;
+export declare function pullSnapshot(rootInput: string, snapshot: MemorySyncSnapshot, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<{
+    changed: number;
+    conflicts: number;
+    cursor: string;
+    dryRun: boolean;
+}>;
+export declare function pullChanges(rootInput: string, delta: MemorySyncChanges, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<{
+    changed: number;
+    conflicts: number;
+    cursor: string;
+    dryRun: boolean;
+}>;
+export declare function planPush(rootInput: string, { recordConflicts }?: {
+    recordConflicts?: boolean;
+}): Promise<{
+    manifest: MemorySyncManifest;
+    mutations: LocalMutation[];
+    conflicts: number;
+    unrecognizedFiles: string[];
+    nextActions: string[];
+}>;
+export declare function syncStatus(rootInput: string): Promise<Record<string, unknown>>;
+export declare function stageLocalDelete(rootInput: string, memoryId: string): Promise<{
+    memoryId: string;
+    file: string;
+    expectedVersionId: string;
+    tombstoneFile: string;
+}>;
+export declare function resolveConflict(rootInput: string, conflictId: string, strategy: string, manualContent?: string): Promise<{
+    resolved: boolean;
+    strategy: string;
+}>;
+export declare function revokeMaterialization(rootInput: string, generation: number): Promise<{
+    removed: number;
+}>;
+export declare function boundedFinalFlush<T>(flush: () => Promise<T>, timeoutMs?: number): Promise<{
+    flushed: boolean;
+    result?: T;
+    unsynced?: true;
+}>;