@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/lib/space-loop-migration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converting a Space's older periodic agent turns into Space loops on the CLI
+ * (OSK-18009, design §5.11): how `skrr spaces loops migrate` prints a plan and
+ * what applying it did.
+ *
+ * The vocabulary (dispositions, reasons, outcomes) and every sentence that
+ * explains a code are `@skrr-ai/data-provider`'s (`spaces/loopMigration.ts`),
+ * and the server sends each code's sentence beside it; this file only lays
+ * them out. A label, a prompt or a note was written by a person or an agent
+ * and is printed as data, on one line.
+ */
+import type { SpaceLoopMigrationApplyResponse, SpaceLoopMigrationPlan } from '@skrr-ai/data-provider';
+/** The plan, as a person reviews it before applying. */
+export declare function planLines(plan: SpaceLoopMigrationPlan, { binName }?: {
+    binName?: string;
+}): string[];
+/** What applying did, one line per entry. */
+export declare function applyLines(response: SpaceLoopMigrationApplyResponse): string[];

package/dist/lib/space-loop-migration.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planLines = planLines;
+exports.applyLines = applyLines;
+const space_notebook_1 = require("./space-notebook");
+const SHAPE_WORD = {
+    space_loop: "the Space's loop",
+    member_automation: "its owner's own Commitment, delivering into the Space",
+};
+const OUTCOME_WORD = {
+    handed_over: 'handed over',
+    awaiting_activation: 'loop made, not active yet',
+    already_handed_over: 'already handed over',
+    not_converted: 'not converted',
+    not_yours: 'not yours to convert',
+    abandoned: 'its loop ended before taking over',
+    failed: 'failed',
+};
+function perDay(value) {
+    if (value >= 1)
+        return `${Math.round(value * 100) / 100}/day`;
+    return `1 every ${Math.round(1 / value)} days`;
+}
+function entryHeading(entry) {
+    return `  ${entry.entryId}  ${(0, space_notebook_1.oneLine)(entry.label, 80)}`;
+}
+function convertLines(entry) {
+    const lines = [entryHeading(entry)];
+    const target = entry.target;
+    if (target) {
+        lines.push(`    becomes   ${SHAPE_WORD[target.shape] || target.shape}: owned by user ${target.ownerUserId}, held by agent ${target.agentId}`);
+    }
+    if (entry.pointer) {
+        lines.push(`    loop      ${entry.pointer.commitmentId} (${entry.pointer.loopStatus || 'unknown'}); the entry keeps firing until it is active`);
+    }
+    const cadence = entry.cadence;
+    if (cadence) {
+        lines.push(`    cadence   ${cadence.fidelity}: ${(0, space_notebook_1.oneLine)(cadence.before.summary, 80)}, ${perDay(cadence.before.turnsPerDay)} -> ${(0, space_notebook_1.oneLine)(cadence.after.summary, 100)}, ${perDay(cadence.after.turnsPerDay)}`);
+        for (const note of cadence.notes)
+            lines.push(`              ${(0, space_notebook_1.oneLine)(note.message, 200)}`);
+    }
+    for (const note of entry.notes)
+        lines.push(`    differs   ${(0, space_notebook_1.oneLine)(note.message, 200)}`);
+    if (entry.activation?.knownBlockers?.length) {
+        lines.push(`    activate  will stay a draft until fixed: ${entry.activation.knownBlockers.join(', ')} (the entry keeps firing meanwhile)`);
+    }
+    lines.push(entry.apply.allowed
+        ? '    apply     you can apply this'
+        : `    apply     not you: ${(0, space_notebook_1.oneLine)(entry.apply.message || entry.apply.reason, 200)}`);
+    return lines;
+}
+/** The plan, as a person reviews it before applying. */
+function planLines(plan, { binName = 'skrr' } = {}) {
+    const lines = [
+        `Converting ${plan.sourceLabel} entries of space ${plan.spaceId} into Space loops`,
+        plan.executionPrincipal
+            ? `Execution principal: user ${plan.executionPrincipal.userId} (version ${plan.executionPrincipal.version}). Their entries become the Space's loops; everyone else's become their own Commitments.`
+            : "This Space has no active execution principal, so every entry becomes its owner's own Commitment.",
+    ];
+    if (plan.entryScope === 'owner') {
+        lines.push(`A ${plan.sourceLabel} is private to its member: this plan lists only yours, and each member converts their own.`);
+    }
+    const groups = [
+        ['Will convert', plan.entries.filter((entry) => entry.disposition === 'convert')],
+        [
+            'Converted, loop not active yet',
+            plan.entries.filter((entry) => entry.disposition === 'resume'),
+        ],
+        ['Handed over', plan.entries.filter((entry) => entry.disposition === 'handed_over')],
+        ['Not converted', plan.entries.filter((entry) => entry.disposition === 'not_convertible')],
+    ];
+    for (const [title, entries] of groups) {
+        if (entries.length === 0)
+            continue;
+        lines.push('', `${title} (${entries.length}):`);
+        for (const entry of entries) {
+            if (entry.disposition === 'convert' || entry.disposition === 'resume') {
+                lines.push(...convertLines(entry));
+            }
+            else if (entry.disposition === 'handed_over') {
+                const status = entry.pointer?.loopStatus;
+                lines.push(`${entryHeading(entry)}: retired, replaced by loop ${entry.pointer?.commitmentId} (${status || 'unknown'})${status && status !== 'active' && status !== 'paused'
+                    ? '. A retired entry stays retired; make a new loop or heartbeat to bring the turn back.'
+                    : ''}`);
+            }
+            else {
+                // A short detail reads inline; a long one (which events and filters
+                // block a Space assistant, OSK-18010) gets its own line, never cut short.
+                const detail = entry.detail ? (0, space_notebook_1.oneLine)(entry.detail, 600) : '';
+                const inline = detail && detail.length <= 160;
+                lines.push(`${entryHeading(entry)}: ${(0, space_notebook_1.oneLine)(entry.message || entry.reason, 240)}${inline ? ` (${detail})` : ''}`);
+                if (detail && !inline)
+                    lines.push(`    why       ${detail}`);
+            }
+        }
+    }
+    if (plan.entries.length === 0) {
+        lines.push('', plan.entryScope === 'owner'
+            ? `You have no ${plan.sourceLabel} in this space.`
+            : `No ${plan.sourceLabel} entries in this space.`);
+    }
+    lines.push('', `Plan digest: ${plan.planDigest}`);
+    if (plan.counts.applicableByYou > 0) {
+        lines.push(`Apply the ${plan.counts.applicableByYou} you can: ${binName} spaces loops migrate ${plan.spaceId} --from ${plan.source} --apply --plan-digest ${plan.planDigest}`);
+    }
+    else {
+        lines.push('Nothing here is yours to apply.');
+    }
+    return lines;
+}
+/** What applying did, one line per entry. */
+function applyLines(response) {
+    const lines = response.results.map((result) => {
+        const word = OUTCOME_WORD[result.outcome] || result.outcome;
+        const loop = result.commitmentId ? ` -> loop ${result.commitmentId}` : '';
+        const code = result.code ? ` (${result.code})` : '';
+        const detail = result.detail ? `: ${(0, space_notebook_1.oneLine)(result.detail, 240)}` : '';
+        return `${result.entryId}  ${word}${loop}${code}${detail}`;
+    });
+    const counts = Object.entries(response.counts)
+        .map(([outcome, count]) => `${count} ${OUTCOME_WORD[outcome] || outcome}`)
+        .join(', ');
+    lines.push('', counts || 'Nothing to apply.');
+    if (response.results.some((result) => result.outcome === 'awaiting_activation')) {
+        lines.push('A loop that is not active yet leaves its entry firing. Fix what the code names, then activate the loop; its entry retires the moment it is active.');
+    }
+    return lines;
+}

package/dist/lib/space-notebook.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The Space Notebook on the CLI (OSK-17996): how `skrr spaces notebook` prints
+ * one page of a Space's timeline.
+ *
+ * The vocabulary, the link paths and the sentences that explain why a kind
+ * ends where it does are `@skrr-ai/data-provider`'s (`spaces/notebook.ts`);
+ * this file only lays them out, so the CLI cannot describe a window or a
+ * visibility rule differently from the web Notebook tab.
+ *
+ * A row's summary was written by a person, an Agent or the platform (its
+ * author says which) and is printed as data: on one line, control characters
+ * removed, so a summary cannot forge a row of its own.
+ */
+import { type SpaceNotebookAuthor, type SpaceNotebookResponse } from '@skrr-ai/data-provider';
+/** One printable line: no control or bidi characters, whitespace collapsed. */
+export declare function oneLine(value: unknown, max?: number): string;
+export declare function notebookAuthorLabel(author: SpaceNotebookAuthor | undefined): string;
+/** The lines `spaces notebook` prints for one page. */
+export declare function notebookLines(page: SpaceNotebookResponse, { webOrigin, binName }: {
+    webOrigin?: string;
+    binName: string;
+}): string[];

package/dist/lib/space-notebook.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oneLine = oneLine;
+exports.notebookAuthorLabel = notebookAuthorLabel;
+exports.notebookLines = notebookLines;
+/**
+ * The Space Notebook on the CLI (OSK-17996): how `skrr spaces notebook` prints
+ * one page of a Space's timeline.
+ *
+ * The vocabulary, the link paths and the sentences that explain why a kind
+ * ends where it does are `@skrr-ai/data-provider`'s (`spaces/notebook.ts`);
+ * this file only lays them out, so the CLI cannot describe a window or a
+ * visibility rule differently from the web Notebook tab.
+ *
+ * A row's summary was written by a person, an Agent or the platform (its
+ * author says which) and is printed as data: on one line, control characters
+ * removed, so a summary cannot forge a row of its own.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+const KIND_TAG = {
+    task_result: 'result',
+    loop_cycle: 'cycle',
+    hypothesis: 'hypothesis',
+    journal_entry: 'journal',
+    report: 'report',
+};
+const VERDICT_WORD = {
+    supported: 'supported',
+    refuted: 'ruled out',
+    inconclusive: 'inconclusive',
+    superseded: 'superseded',
+};
+/** One printable line: no control or bidi characters, whitespace collapsed. */
+function oneLine(value, max = 240) {
+    const text = String(value ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f-\u009f‎‏‪-‮⁦-⁩]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+function notebookAuthorLabel(author) {
+    if (!author)
+        return 'unknown';
+    if (author.kind === 'agent')
+        return author.agentId ? `agent ${author.agentId}` : 'agent';
+    if (author.kind === 'person')
+        return author.userId ? `person ${author.userId}` : 'person';
+    return author.label ? `system (${oneLine(author.label, 60)})` : 'system';
+}
+const LINK_WORD = {
+    home: 'loop of this Space',
+    watch: 'watching this Space',
+};
+const VISIBILITY_WORD = {
+    space_access: 'shared with the Space',
+    commitment_access: 'only for people who can open the Commitment',
+};
+/** Which Commitment a loop row came from, and who may see the row. */
+function loopLine(row) {
+    const link = LINK_WORD[row.loop.link] || row.loop.link;
+    const seen = VISIBILITY_WORD[row.visibility] || row.visibility;
+    return `${link} · ${seen}`;
+}
+function detailLines(row) {
+    switch (row.kind) {
+        case 'task_result': {
+            const task = row.task.identifier || row.task.id;
+            const conclusion = row.result.conclusionType ? `, ${row.result.conclusionType}` : '';
+            const current = row.result.current ? '' : ', superseded';
+            return [`task ${task}, result v${row.result.version}${conclusion}${current}`];
+        }
+        case 'loop_cycle': {
+            const stop = row.cycle.stop;
+            const lines = [
+                stop
+                    ? `stopped at ${stop.question}/${stop.gate}${stop.reason ? ` (${stop.reason})` : ''}`
+                    : 'an agent turn was dispatched',
+            ];
+            if (stop?.fix)
+                lines.push(`fix: ${oneLine(stop.fix)}`);
+            lines.push(loopLine(row));
+            return lines;
+        }
+        case 'hypothesis': {
+            const word = VERDICT_WORD[row.verdict.status] || row.verdict.status;
+            const by = row.verdict.authority === 'observation_backed' ? 'settled by readings' : 'agent-reported';
+            const lines = [`verdict: ${word} (${by})`];
+            if (row.verdict.reason)
+                lines.push(`because: ${oneLine(row.verdict.reason)}`);
+            lines.push(loopLine(row));
+            return lines;
+        }
+        default:
+            return [];
+    }
+}
+/** The lines `spaces notebook` prints for one page. */
+function notebookLines(page, { webOrigin, binName }) {
+    const lines = [];
+    if (!page.rows.length) {
+        lines.push(page.nextCursor
+            ? 'Nothing on this page.'
+            : `No available records in this listing (${page.kinds.map(data_provider_1.spaceNotebookKindLabel).join(', ')}).`);
+    }
+    for (const row of page.rows) {
+        const tag = (KIND_TAG[row.kind] || row.kind).padEnd(10);
+        lines.push(`${row.at}  ${tag}  ${oneLine(row.title, 80)}  · ${notebookAuthorLabel(row.author)}`);
+        if (row.summary) {
+            lines.push(`    ${oneLine(row.summary)}${row.summaryTruncated ? ' (cut; open it for the rest)' : ''}`);
+        }
+        for (const detail of detailLines(row))
+            lines.push(`    ${detail}`);
+        lines.push(`    ${webOrigin ? `${webOrigin}${row.link.path}` : row.link.path}`);
+    }
+    const notes = [];
+    for (const source of page.sources) {
+        if (source.state !== 'ended')
+            continue;
+        for (const window of source.windows || []) {
+            notes.push((0, data_provider_1.describeSpaceNotebookWindow)(source.kind, window));
+        }
+    }
+    // Who may see a loop row, once per rule the page shows.
+    for (const row of page.rows) {
+        if ('visibility' in row && row.visibility) {
+            notes.push((0, data_provider_1.describeSpaceNotebookVisibility)(row.visibility));
+        }
+    }
+    lines.push('', ...[...new Set(notes)], data_provider_1.SPACE_NOTEBOOK_COVERAGE_NOTE);
+    if (page.nextCursor) {
+        // A cursor is bound to the filter it was issued for; every kind is the
+        // default, so the flag is only repeated when the page was filtered.
+        const kinds = page.kinds.length && page.kinds.length < data_provider_1.SPACE_NOTEBOOK_KINDS.length
+            ? ` --kinds ${page.kinds.join(',')}`
+            : '';
+        lines.push('', `More: ${binName} spaces notebook ${page.spaceId}${kinds} --cursor ${page.nextCursor}`);
+    }
+    return lines;
+}

package/dist/lib/space-proposal-decision-command.d.ts

@@ -0,0 +1,36 @@
+import { BaseCommand } from '../base-command';
+import { type SpaceProposalDecision } from './space-proposals';
+/**
+ * The flags `keep` and `discard` share. Exported so each command spreads it
+ * into its own `flags`: the command-hygiene scan reads one file at a time and
+ * recognises a shared `...xFlags` spread, not a static inherited from a class.
+ */
+export declare const spaceProposalDecisionFlags: {
+    expected: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'reason-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * `skrr spaces proposals keep|discard <space> <KIND:ID>` (OSK-17993).
+ *
+ * Reads the item from the Space's inbox, then sends the decision to the
+ * endpoint the item names (`decisionRoute`): the owning object's own. The CLI
+ * decides nothing itself and adds no decision path. An Action Bundle is pinned
+ * to `--expected`, the revision the caller reviewed in `list`: deciding the
+ * bundle as it is NOW would approve writes the caller never saw.
+ */
+export declare abstract class SpaceProposalDecisionCommand extends BaseCommand {
+    static decision: SpaceProposalDecision;
+    static args: {
+        space: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        item: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        expected: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'reason-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/lib/space-proposal-decision-command.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpaceProposalDecisionCommand = exports.spaceProposalDecisionFlags = void 0;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../base-command");
+const space_proposals_1 = require("./space-proposals");
+/**
+ * The flags `keep` and `discard` share. Exported so each command spreads it
+ * into its own `flags`: the command-hygiene scan reads one file at a time and
+ * recognises a shared `...xFlags` spread, not a static inherited from a class.
+ */
+exports.spaceProposalDecisionFlags = {
+    expected: core_1.Flags.string({
+        description: 'For an Action Bundle: the exact REVISION JSON that `spaces proposals list` printed for it',
+    }),
+    reason: core_1.Flags.string({ description: 'Why (recorded with the decision)' }),
+    'reason-code': core_1.Flags.string({ options: [...data_provider_1.PROPOSAL_DISCARD_REASON_CODES] }),
+    json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+};
+/**
+ * `skrr spaces proposals keep|discard <space> <KIND:ID>` (OSK-17993).
+ *
+ * Reads the item from the Space's inbox, then sends the decision to the
+ * endpoint the item names (`decisionRoute`): the owning object's own. The CLI
+ * decides nothing itself and adds no decision path. An Action Bundle is pinned
+ * to `--expected`, the revision the caller reviewed in `list`: deciding the
+ * bundle as it is NOW would approve writes the caller never saw.
+ */
+class SpaceProposalDecisionCommand extends base_command_1.BaseCommand {
+    static decision;
+    static args = {
+        space: core_1.Args.string({
+            description: 'Space ID, or a title to resolve',
+            required: true,
+            ignoreStdin: true,
+        }),
+        item: core_1.Args.string({
+            description: 'The KIND:ID that `spaces proposals list` prints',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = exports.spaceProposalDecisionFlags;
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(this.constructor);
+        const decision = this.constructor.decision;
+        let expected;
+        if (flags.expected !== undefined) {
+            try {
+                expected = JSON.parse(flags.expected);
+            }
+            catch {
+                this.failWithCliError({
+                    message: '--expected must be the revision JSON `spaces proposals list` printed.',
+                    code: 'PROPOSAL_EXPECTED_INVALID',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+        }
+        const spaceId = await this.resolveSpaceReference(args.space);
+        let item;
+        try {
+            item = await space_proposals_1.spaceProposalsApi.show(spaceId, args.item);
+        }
+        catch (error) {
+            if (error?.status === 404) {
+                this.failWithCliError({
+                    message: `No proposal ${args.item} is in this space's inbox for you. ` +
+                        '`spaces proposals list` prints each as KIND:ID.',
+                    code: 'PROPOSAL_NOT_FOUND',
+                    status: 404,
+                    exit: 4,
+                    retryable: false,
+                });
+            }
+            this.handleApiError(error);
+        }
+        let result;
+        try {
+            result = await space_proposals_1.spaceProposalsApi.decide(item, {
+                decision,
+                expected,
+                reason: flags.reason,
+                reasonCode: flags['reason-code'],
+            });
+        }
+        catch (error) {
+            if (error instanceof space_proposals_1.SpaceProposalDecisionError) {
+                this.failWithCliError({
+                    message: error.message,
+                    code: error.code,
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            this.handleApiError(error);
+        }
+        if (flags.json) {
+            this.printJsonResult({ item: item.id, decision, result });
+            return;
+        }
+        this.log(`Proposal ${item.id}: ${decision} recorded by its own service.`);
+    }
+}
+exports.SpaceProposalDecisionCommand = SpaceProposalDecisionCommand;

package/dist/lib/space-proposals.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The Space proposals inbox on the CLI (OSK-17993): `skrr spaces proposals
+ * list|keep|discard`.
+ *
+ * The inbox is a READ-TIME projection (`GET /api/spaces/:spaceId/proposals`).
+ * It has no decision endpoint of its own, and neither does this file: a keep
+ * or discard is sent to the endpoint the ITEM names (`decisionRoute`), which
+ * is the owning object's existing one, and that endpoint authorizes the
+ * decider. One entry per route kind in `DECIDERS`; the record type makes a
+ * new route kind fail to compile here until it is given one.
+ */
+import { type ProposalDiscardReasonCode, type ProposalRevision, type SpaceProposalListParams, type SpaceProposalListResponse, type SpaceProposalView } from '@skrr-ai/data-provider';
+export type SpaceProposalDecision = 'keep' | 'discard';
+export type SpaceProposalDecisionInput = {
+    decision: SpaceProposalDecision;
+    /** The revision the caller reviewed (Action Bundles only). */
+    expected?: ProposalRevision;
+    reason?: string;
+    reasonCode?: ProposalDiscardReasonCode;
+};
+export declare class SpaceProposalDecisionError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare const spaceProposalsApi: {
+    list(spaceId: string, params?: SpaceProposalListParams): Promise<SpaceProposalListResponse>;
+    show(spaceId: string, itemId: string): Promise<SpaceProposalView>;
+    /**
+     * Send one decision to the endpoint `item.decisionRoute` names. Refuses
+     * before any transport when the item says the caller cannot take it.
+     */
+    decide(item: SpaceProposalView, input: SpaceProposalDecisionInput): Promise<unknown>;
+};
+/** The attribution line of a Memory proposal the platform made, or null for the Agent's own. */
+export declare function spaceMemoryProducerLine(item: SpaceProposalView): string | null;
+/** One row of `spaces proposals list`, in the order printed. */
+export declare function spaceProposalRow(item: SpaceProposalView): Record<string, string>;
+/**
+ * The lines under the table: the writes each held bundle would make here, and,
+ * for a bundle the caller can decide, the exact revision to pin `keep` to.
+ */
+export declare function spaceProposalDetailLines(item: SpaceProposalView, binName: string): string[];
+/** What an empty page means: "none" only once the inbox is exhausted. */
+export declare function emptySpaceInboxLines(nextCursor: string | null | undefined): string[];