@skrr-ai/cli 0.1.22 → 0.1.24

package/dist/lib/harnesses.js

@@ -7,6 +7,7 @@ exports.getHarnessModels = getHarnessModels;
 exports.listHarnessProducts = listHarnessProducts;
 exports.getHarnessUsage = getHarnessUsage;
 exports.getAllHarnessUsage = getAllHarnessUsage;
+exports.getRuntimeMonthlySpend = getRuntimeMonthlySpend;
 exports.listQuotaAccounts = listQuotaAccounts;
 exports.getQuotaHistory = getQuotaHistory;
 exports.updateHarness = updateHarness;
@@ -71,6 +72,18 @@ async function getAllHarnessUsage() {
     const ownerWide = '?scope=all';
     return (0, api_fetch_1.apiFetch)('/api/harnesses/usage/aggregate' + ownerWide);
 }
+/**
+ * The monthly runtime spend cap, read before it refuses anything.
+ *
+ * Distinct from the balance's own spend cap, which is a per-period RATE LIMIT
+ * on credits. A user can have headroom on that one and still be refused by
+ * this one, which is exactly what happened: every number on `balance show`
+ * said there was room while a monthly hosted-runtime cap turned every turn
+ * away (OSK-7920).
+ */
+async function getRuntimeMonthlySpend() {
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/spend');
+}
 /** The CLI subscription accounts this user's daemons have reported readings for. */
 async function listQuotaAccounts() {
     return (0, api_fetch_1.apiFetch)('/api/harnesses/quota/accounts');
@@ -149,7 +162,25 @@ async function readHarnessPing(id, pingId) {
     return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/ping/${encodeURIComponent(pingId)}`);
 }
 // ── Leases (hosted billing plane) ──────────────────────────────────────────
-async function listHarnessLeases() {
+/**
+ * List leases. The server answers newest-first and caps at 50 unless asked
+ * otherwise (`Math.min(Math.max(Number(limit) || 50, 1), 100)`), so an account
+ * with more than fifty leases could not see past the newest fifty from here —
+ * including `lost` ones, which are terminal, invisible, and still billed for
+ * the whole window the platform had lost track of them.
+ */
+async function listHarnessLeases(options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit)
+        query.set('limit', String(options.limit));
+    if (options.state)
+        query.set('state', options.state);
+    if (options.machineProduct)
+        query.set('machineProduct', options.machineProduct);
+    const encoded = query.toString();
+    if (encoded) {
+        return (0, api_fetch_1.apiFetch)(`/api/machines/leases?${encoded}`);
+    }
     return (0, api_fetch_1.apiFetch)('/api/machines/leases');
 }
 async function getHarnessLease(leaseId) {

package/dist/lib/hosted-machines.js

@@ -237,6 +237,15 @@ async function waitForHostedMachineReady(id, options) {
             const detail = hostedMachineErrorSummary(session);
             throw new Error(`Hosted Machine ${id} reached ${status}${detail ? `: ${detail}` : ''}`);
         }
+        // Async resume deliberately rolls a recoverable failure back to `paused`
+        // so the retained workspace remains resumable. That is terminal for THIS
+        // wait operation even though it is not terminal for the machine. The
+        // resuming transition clears old error state, so an error-bearing paused
+        // row here belongs to the attempt we just started.
+        if (status === 'paused') {
+            const detail = hostedMachineErrorSummary(session);
+            throw new Error(`Hosted Machine ${id} returned to paused before it became ready${detail ? `: ${detail}` : ''}`);
+        }
         if (options.timeoutMs && Date.now() - startedAt >= options.timeoutMs) {
             throw new HostedMachineReadyTimeoutError(id, hostedMachineProgressSummary(session));
         }

package/dist/lib/inbox.d.ts

@@ -4,7 +4,8 @@
  * Gap analysis §3.3 (b): *"50 个命令组中没有 `skrr inbox` / `listen` / `tail` /
  * `notify`，CLI 全是 pull"*. The audit's third use case wants an agent that
  * *"像真人一样时不时发两三条消息"* — and the reply half of that loop already
- * works (`skrr agents chat --conversation <id>` stamps `Message.intentId` and
+ * works (`skrr agents chat <agent-id> --conversation <id> --prompt "…"` stamps
+ * `Message.intentId` and
  * wakes the originating run). What was missing is the other direction: nothing
  * in the CLI ever told you the agent had said something.
  *

package/dist/lib/machines.d.ts

@@ -87,6 +87,23 @@ export interface Machine {
         canTerminate: boolean;
     };
 }
+/**
+ * What a machine's state actually is, when `offline` is doing two jobs.
+ *
+ * A TERMINATED ephemeral sandbox — destroyed, unrecoverable, `canResume:
+ * false`, no lease — rendered `offline`, identically to a machine that is
+ * merely not connected right now. Those are opposite situations: one can come
+ * back and one never will, and the board's original target turned out to be the
+ * second while every surface said the first. The only way to learn the
+ * difference was to run `skrr machines hosted list` separately and match
+ * sandbox ids by hand (OSK-7639).
+ *
+ * `canResume` is the discriminator the payload already carries: a machine that
+ * could come back says so, and a destroyed one cannot.
+ */
+export declare function machineStateLabel(machine: Machine): string;
+/** Is this a machine a user could still use, or bring back? */
+export declare function isReachableMachine(machine: Machine): boolean;
 /** The user-editable slice. Identities, capabilities and lifecycle are not. */
 export interface MachinePreferencesPatch {
     name?: string;

package/dist/lib/machines.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.machineStateLabel = machineStateLabel;
+exports.isReachableMachine = isReachableMachine;
 exports.liveHarnessCount = liveHarnessCount;
 exports.listMachines = listMachines;
 exports.getMachine = getMachine;
@@ -7,6 +9,33 @@ exports.updateMachine = updateMachine;
 exports.disconnectMachine = disconnectMachine;
 exports.resolveMachineRef = resolveMachineRef;
 const api_fetch_1 = require("./api-fetch");
+/**
+ * What a machine's state actually is, when `offline` is doing two jobs.
+ *
+ * A TERMINATED ephemeral sandbox — destroyed, unrecoverable, `canResume:
+ * false`, no lease — rendered `offline`, identically to a machine that is
+ * merely not connected right now. Those are opposite situations: one can come
+ * back and one never will, and the board's original target turned out to be the
+ * second while every surface said the first. The only way to learn the
+ * difference was to run `skrr machines hosted list` separately and match
+ * sandbox ids by hand (OSK-7639).
+ *
+ * `canResume` is the discriminator the payload already carries: a machine that
+ * could come back says so, and a destroyed one cannot.
+ */
+function machineStateLabel(machine) {
+    if (machine.status !== 'offline')
+        return machine.status;
+    const controls = machine.controls;
+    if (controls && controls.canResume === false && controls.canTerminate === false) {
+        return 'terminated';
+    }
+    return 'offline';
+}
+/** Is this a machine a user could still use, or bring back? */
+function isReachableMachine(machine) {
+    return machineStateLabel(machine) !== 'terminated' && machine.status !== 'offline';
+}
 /**
  * How many of a machine's harnesses still represent a capability it has.
  *

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;
+}>;