@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/lib/space-proposals.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spaceProposalsApi = exports.SpaceProposalDecisionError = void 0;
+exports.spaceMemoryProducerLine = spaceMemoryProducerLine;
+exports.spaceProposalRow = spaceProposalRow;
+exports.spaceProposalDetailLines = spaceProposalDetailLines;
+exports.emptySpaceInboxLines = emptySpaceInboxLines;
+/**
+ * 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.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+class SpaceProposalDecisionError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SpaceProposalDecisionError';
+    }
+}
+exports.SpaceProposalDecisionError = SpaceProposalDecisionError;
+const DECIDERS = {
+    // The Proposal Inbox's own decision endpoint, pinned to the reviewed revision.
+    proposal_inbox: (route, input) => {
+        if (!input.expected) {
+            throw new SpaceProposalDecisionError('This proposal is decided against the exact revision you reviewed: pass --expected with ' +
+                'the REVISION JSON that `spaces proposals list` printed for it.', 'PROPOSAL_EXPECTED_REQUIRED');
+        }
+        return data_provider_1.dataService.decideProposal(route.kind, route.sourceId, {
+            decision: input.decision,
+            expected: input.expected,
+            ...(input.reason ? { reason: input.reason } : {}),
+            ...(input.reasonCode ? { reasonCode: input.reasonCode } : {}),
+            via: 'cli',
+        });
+    },
+    // A suggestion on a page (OSK-17997): its own decision endpoint. Keep is
+    // accept, which applies a page revision proposal to the page.
+    doc_suggestion: (route, input) => data_provider_1.dataService.decideDocCommentSuggestion({
+        docType: route.docType,
+        docId: route.docId,
+        threadId: route.threadId,
+        decision: input.decision === 'keep' ? 'accept' : 'reject',
+    }),
+    // The Memory Store's own commit/reject, through the Agent that proposed it.
+    memory_store_proposal: (route, input) => {
+        if (!route.agentId) {
+            throw new SpaceProposalDecisionError('This Memory proposal names no Agent to decide it through.', 'PROPOSAL_DECISION_UNAVAILABLE');
+        }
+        return data_provider_1.dataService.decideAgentMemoryStoreProposal(route.agentId, route.storeId, route.proposalId, input.decision === 'keep' ? 'commit' : 'reject', { spaceId: route.spaceId, ...(input.reason ? { reason: input.reason } : {}) });
+    },
+    // The Learning service's own doors on the Space's lessons (OSK-17998), pinned
+    // to the version the item was listed at. The key is the decision on that
+    // version, so a retry replays rather than deciding twice.
+    space_lesson: (route, input) => {
+        const idempotencyKey = (0, data_provider_1.spaceLessonDecisionKey)(input.decision, route);
+        if (input.decision === 'keep') {
+            return data_provider_1.dataService.promoteSpaceLesson(route.spaceId, route.storeId, route.memoryId, {
+                expectedVersionId: route.expectedVersionId,
+                idempotencyKey,
+            });
+        }
+        return data_provider_1.dataService.dismissSpaceLesson(route.spaceId, route.storeId, route.memoryId, {
+            expectedVersionId: route.expectedVersionId,
+            idempotencyKey,
+            reason: data_provider_1.SPACE_LESSON_DISMISS_REASON_FOR[input.reasonCode || 'other'],
+            ...(input.reason ? { note: input.reason } : {}),
+        });
+    },
+};
+exports.spaceProposalsApi = {
+    list(spaceId, params = {}) {
+        return data_provider_1.dataService.listSpaceProposals(spaceId, params);
+    },
+    show(spaceId, itemId) {
+        return data_provider_1.dataService.getSpaceProposal(spaceId, itemId);
+    },
+    /**
+     * Send one decision to the endpoint `item.decisionRoute` names. Refuses
+     * before any transport when the item says the caller cannot take it.
+     */
+    decide(item, input) {
+        if (!item.canDecide || !item.availableDecisions.includes(input.decision)) {
+            const why = item.undecidableReason
+                ? data_provider_1.PROPOSAL_UNDECIDABLE_TEXT[item.undecidableReason]
+                : `It does not take "${input.decision}"`;
+            throw new SpaceProposalDecisionError(`You cannot ${input.decision} ${item.id}: ${why}.`, 'PROPOSAL_DECISION_UNAVAILABLE');
+        }
+        const route = item.decisionRoute;
+        const decider = DECIDERS[route.via];
+        if (!decider) {
+            throw new SpaceProposalDecisionError(`This CLI does not know how to decide a ${route.via} item; update skrr.`, 'PROPOSAL_DECISION_ROUTE_UNKNOWN');
+        }
+        return decider(route, input);
+    },
+};
+/**
+ * Who made a Space Memory proposal when it was not the Agent it names
+ * (OSK-18000, `memory.producer`). The Agent is named as the one it was filed
+ * through, never as its author. A producer this build predates is shown by its
+ * own name.
+ */
+const MEMORY_PRODUCER_TEXT = {
+    autodream: 'suggested by the daily memory consolidation for this space',
+};
+/** The attribution line of a Memory proposal the platform made, or null for the Agent's own. */
+function spaceMemoryProducerLine(item) {
+    const producer = item.kind === 'memory_proposal' ? item.memory?.producer : undefined;
+    if (!producer)
+        return null;
+    const said = MEMORY_PRODUCER_TEXT[producer] || `suggested by the platform (${producer})`;
+    const agent = item.agent?.name || item.agent?.id;
+    return agent ? `${said}, filed through agent ${agent}` : said;
+}
+const SCOPE_LABEL = {
+    space_write: 'held write',
+    space_loop: 'space loop',
+    space_memory: 'memory',
+    space_page: 'page',
+    space_skill: 'skill',
+};
+/** One row of `spaces proposals list`, in the order printed. */
+function spaceProposalRow(item) {
+    let note = '—';
+    if (item.canDecide)
+        note = 'you can decide';
+    else if (item.undecidableReason && item.undecidableReason !== 'settled')
+        note = data_provider_1.PROPOSAL_UNDECIDABLE_TEXT[item.undecidableReason];
+    const scope = item.scopes.map((value) => SCOPE_LABEL[value] || value).join(', ');
+    const elsewhere = item.writesElsewhere
+        ? ` (+${item.writesElsewhere} write${item.writesElsewhere === 1 ? '' : 's'} elsewhere)`
+        : '';
+    return {
+        id: item.id,
+        title: `${item.title}${elsewhere}`,
+        scope,
+        disposition: item.disposition,
+        deadline: item.deadline || '—',
+        note,
+    };
+}
+/**
+ * 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.
+ */
+function spaceProposalDetailLines(item, binName) {
+    const lines = [];
+    for (const write of item.writes || []) {
+        lines.push(`  ${item.id}  ${write.operation} ${write.title || write.taskId || ''}`.trimEnd());
+    }
+    if (item.kind === 'memory_proposal' && item.memory?.claim) {
+        lines.push(`  ${item.id}  ${item.memory.path || ''}: ${item.memory.claim}`.trimEnd());
+    }
+    const produced = spaceMemoryProducerLine(item);
+    if (produced)
+        lines.push(`  ${item.id}  ${produced}`);
+    if (item.kind === 'page_suggestion' && item.page) {
+        const where = item.page.anchor
+            ? (0, data_provider_1.describePageSectionAnchor)(item.page.anchor)
+            : 'the marked text';
+        lines.push(`  ${item.id}  ${item.page.pageTitle || item.page.pageId}: ${where}`);
+        if (item.page.truncated)
+            lines.push(`  ${item.id}  (texts shortened here; open the page to read all of it)`);
+    }
+    if (item.kind === 'space_lesson' && item.lesson) {
+        const steps = item.lesson.steps === 1 ? '1 step' : `${item.lesson.steps ?? 0} steps`;
+        lines.push(`  ${item.id}  skill: ${item.lesson.goal || item.title} (${steps})`);
+    }
+    if (item.canDecide && item.decisionRoute.via === 'proposal_inbox') {
+        lines.push(`  ${binName} spaces proposals keep ${item.spaceId} ${item.id} --expected '${JSON.stringify(item.decisionRoute.expected)}'`);
+    }
+    return lines;
+}
+/** What an empty page means: "none" only once the inbox is exhausted. */
+function emptySpaceInboxLines(nextCursor) {
+    return nextCursor
+        ? ['No proposals on this page; the cursor below continues.']
+        : ['No proposals for this space.'];
+}

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

@@ -6,6 +6,7 @@
  * "publish" actually sends) are unit-testable without a CLI harness. That is
  * the same split `lib/workflow-templates.ts` uses for the sibling domain.
  */
+import type { InstantiateSpaceTemplateOutcomes } from '@skrr-ai/data-provider';
 export type CliFailure = {
     code: string;
     message: string;
@@ -119,4 +120,11 @@ export declare function buildCreatePayload({ body, title, description, shortDesc
 }): BuildResult<Record<string, unknown>>;
 /** Section name → row count, for the human-readable `show` / `create` output. */
 export declare function summarizeSnapshot(snapshot: unknown): string;
+/**
+ * One line per wiki page an install created as something other than what the
+ * template carried — today, a template charter created as an ordinary page
+ * because the Space already held a live charter. Pages that installed as they
+ * were print nothing; `--json` carries every page's outcome.
+ */
+export declare function wikiPageInstallNotices(outcomes: InstantiateSpaceTemplateOutcomes | undefined): string[];
 export {};

package/dist/lib/space-templates.js

@@ -16,6 +16,8 @@ exports.buildVisibilityPayload = buildVisibilityPayload;
 exports.buildForkPayload = buildForkPayload;
 exports.buildCreatePayload = buildCreatePayload;
 exports.summarizeSnapshot = summarizeSnapshot;
+exports.wikiPageInstallNotices = wikiPageInstallNotices;
+const data_provider_1 = require("@skrr-ai/data-provider");
 /**
  * `slotRef=agentId` pairs → the `agentMapping` record the API takes.
  *
@@ -254,3 +256,18 @@ function summarizeSnapshot(snapshot) {
         .map(([key, value]) => `${value.length} ${key}`);
     return parts.length ? parts.join(', ') : 'empty snapshot';
 }
+const [, INSTALLED_AS_DOC] = data_provider_1.TEMPLATE_WIKI_PAGE_INSTALL_OUTCOMES;
+/**
+ * One line per wiki page an install created as something other than what the
+ * template carried — today, a template charter created as an ordinary page
+ * because the Space already held a live charter. Pages that installed as they
+ * were print nothing; `--json` carries every page's outcome.
+ */
+function wikiPageInstallNotices(outcomes) {
+    return (outcomes?.wikiPages ?? [])
+        .filter((page) => page.outcome === INSTALLED_AS_DOC)
+        .map((page) => {
+        const existing = page.charterPageId ? ` (${page.charterPageId})` : '';
+        return `Note: the template's charter "${page.title}" was added as an ordinary page (${page.pageId}), because this space already has a charter${existing} and a space holds one at a time.`;
+    });
+}

package/dist/lib/space-write-policy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Space write policy on the CLI (OSK-17988): how `skrr spaces write-policy`
+ * prints a policy, and how every task write prints a write the Space held for
+ * approval (`202 { status: 'pending_approval' }`).
+ *
+ * The vocabulary and the effective-mode reading are `@skrr-ai/data-provider`'s
+ * (`spaces/writePolicy.ts`); the server sends the effective rows, and this file
+ * only prints them, so the CLI cannot show a mode the server does not apply.
+ */
+import type { SpaceWritePendingResponse, SpaceWritePolicyResponse } from '@skrr-ai/data-provider';
+/** A task write the Space write policy held for approval (`202`), not a written task. */
+export declare function isSpaceWritePendingResponse(value: unknown): value is SpaceWritePendingResponse;
+/** The lines `spaces write-policy show` prints. */
+export declare function writePolicyLines(view: SpaceWritePolicyResponse): string[];
+/**
+ * The lines a task command prints when the Space held its write for approval.
+ * Says plainly that nothing was written, where the approval is, and how to
+ * look at it.
+ */
+export declare function spaceWritePendingLines(body: SpaceWritePendingResponse, { binName }: {
+    binName: string;
+}): string[];
+/** Map a `--member-automation` / `--principal-automation` value to a stored cell (`default` resets). */
+export declare function cellValue(value: string | undefined): string | null | undefined;

package/dist/lib/space-write-policy.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSpaceWritePendingResponse = isSpaceWritePendingResponse;
+exports.writePolicyLines = writePolicyLines;
+exports.spaceWritePendingLines = spaceWritePendingLines;
+exports.cellValue = cellValue;
+/**
+ * The status a held write answers with. Typed as the contract's own literal, so
+ * a rename in `@skrr-ai/data-provider` fails to compile here; a value rather
+ * than an import so that every task command, which calls this on every write,
+ * does not depend on the package's runtime surface.
+ */
+const PENDING_STATUS = 'pending_approval';
+/** A task write the Space write policy held for approval (`202`), not a written task. */
+function isSpaceWritePendingResponse(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        value.status === PENDING_STATUS &&
+        value.proposal);
+}
+const WRITER_LABEL = {
+    principal_automation: "the Space's own automation (its execution principal)",
+    member_automation: "other members' agents",
+};
+const MODE_LABEL = {
+    auto: 'auto (written at once)',
+    propose: 'propose (held for approval)',
+    refuse: 'refuse',
+};
+/** The lines `spaces write-policy show` prints. */
+function writePolicyLines(view) {
+    const lines = [`Write policy for space ${view.spaceId}`];
+    let currentClass = '';
+    for (const row of view.rows) {
+        if (row.writeClass !== currentClass) {
+            currentClass = row.writeClass;
+            lines.push('', `  ${row.writeClass}`);
+        }
+        const notes = [];
+        if (row.source === 'default')
+            notes.push('default');
+        else
+            notes.push(`set; default ${row.default}`);
+        if (row.capped)
+            notes.push(`the Workspace requires approval for ${row.writeClass}, so stored "auto" reads as propose`);
+        // A class with no proposal path yet refuses what it would hold (OSK-17994);
+        // a page class holds only a body write, as a suggestion (OSK-17997).
+        // `proposalPath` is absent from a server older than the field.
+        if (row.mode === 'propose' && row.proposalPath === null)
+            notes.push('cannot be proposed yet, so an unattended write is refused');
+        if (row.mode === 'propose' && row.proposalPath === 'page_suggestion')
+            notes.push('a body edit becomes a suggestion on the page; other page changes are refused');
+        // OSK-17998: a new skill is proposed as a lesson; nothing else about skills can be.
+        if (row.mode === 'propose' && row.proposalPath === 'space_lesson')
+            notes.push('a new skill is proposed as a lesson a person promotes; a removal or pin is refused');
+        lines.push(`    ${(WRITER_LABEL[row.writerClass] || row.writerClass).padEnd(52)} ${MODE_LABEL[row.mode] || row.mode}  (${notes.join('; ')})`);
+    }
+    if (view.requireApprovalActionClasses.length) {
+        lines.push('', `Workspace approval ceiling: ${view.requireApprovalActionClasses.join(', ')} can never be auto here.`);
+    }
+    lines.push('', 'Interactive writes (a person in the app or at their own CLI) are not governed by this policy.');
+    return lines;
+}
+/**
+ * The lines a task command prints when the Space held its write for approval.
+ * Says plainly that nothing was written, where the approval is, and how to
+ * look at it.
+ */
+function spaceWritePendingLines(body, { binName }) {
+    const proposal = body.proposal;
+    if (proposal.kind === 'page_suggestion') {
+        // A page revision proposal (OSK-17997): a suggestion thread on the page,
+        // decided from the Space inbox or on the page itself.
+        const lines = [
+            'Held for approval: nothing was written yet.',
+            body.message,
+            `Suggestion: ${proposal.id} on page ${proposal.pageId || ''}`.trimEnd(),
+        ];
+        if (proposal.duplicate)
+            lines.push('The same suggestion was already pending; it was not made twice.');
+        if (proposal.spaceId) {
+            lines.push(`Review it: ${binName} spaces proposals list ${proposal.spaceId} --kind page_suggestion`);
+        }
+        return lines;
+    }
+    const lines = [
+        'Held for approval: nothing was written yet.',
+        body.message,
+        `Approval bundle: ${proposal.id} (item ${proposal.itemId})`,
+    ];
+    if (proposal.commitmentId) {
+        lines.push(`Review it: ${binName} commitments action-proposals ${proposal.commitmentId}`);
+    }
+    if (proposal.expiresAt)
+        lines.push(`Expires: ${proposal.expiresAt}`);
+    return lines;
+}
+/** Map a `--member-automation` / `--principal-automation` value to a stored cell (`default` resets). */
+function cellValue(value) {
+    if (value === undefined)
+        return undefined;
+    return value === 'default' ? null : value;
+}

package/dist/lib/task-agent-context-capabilities.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Semantic capabilities advertised by a CLI that can safely render Task Agent
+ * Context recovery instructions. This ships with the CLI (unlike build-only
+ * scripts) so an installed package never depends on the source checkout.
+ *
+ * The release build validates this exact compiled module against the API
+ * catalog and the oclif manifest generated for that release.
+ */
+export declare const TASK_AGENT_CONTEXT_COMMAND_IDS: readonly ["tasks:context", "tasks:preflight", "tasks:show", "tasks:start-receipt", "tasks:retry-receipt"];
+export declare function taskAgentContextCommandCapability(commandId: string): string;

package/dist/lib/task-agent-context-capabilities.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_AGENT_CONTEXT_COMMAND_IDS = void 0;
+exports.taskAgentContextCommandCapability = taskAgentContextCommandCapability;
+/**
+ * Semantic capabilities advertised by a CLI that can safely render Task Agent
+ * Context recovery instructions. This ships with the CLI (unlike build-only
+ * scripts) so an installed package never depends on the source checkout.
+ *
+ * The release build validates this exact compiled module against the API
+ * catalog and the oclif manifest generated for that release.
+ */
+exports.TASK_AGENT_CONTEXT_COMMAND_IDS = [
+    'tasks:context',
+    'tasks:preflight',
+    'tasks:show',
+    'tasks:start-receipt',
+    'tasks:retry-receipt',
+];
+function taskAgentContextCommandCapability(commandId) {
+    return `task-agent-context.command.${commandId.replace(/:/g, '-')}.v1`;
+}

package/dist/lib/task-agent-context-compatibility.d.ts

@@ -0,0 +1,9 @@
+import { type CommandManifest } from './command-manifest';
+export declare const TASK_AGENT_CONTEXT_CAPABILITIES_HEADER = "X-Skrr-Task-Context-Capabilities";
+export declare function taskAgentContextCapabilities(manifest: CommandManifest): string[];
+/**
+ * The header is a UI compatibility declaration, never a permission claim.
+ * If the local manifest cannot be read we advertise nothing and let the
+ * server produce an explicit verification/update recovery state.
+ */
+export declare function taskAgentContextRequestHeaders(rootDir: string): Record<string, string>;

package/dist/lib/task-agent-context-compatibility.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_AGENT_CONTEXT_CAPABILITIES_HEADER = void 0;
+exports.taskAgentContextCapabilities = taskAgentContextCapabilities;
+exports.taskAgentContextRequestHeaders = taskAgentContextRequestHeaders;
+const command_manifest_1 = require("./command-manifest");
+const task_agent_context_capabilities_1 = require("./task-agent-context-capabilities");
+exports.TASK_AGENT_CONTEXT_CAPABILITIES_HEADER = 'X-Skrr-Task-Context-Capabilities';
+function taskAgentContextCapabilities(manifest) {
+    const commands = manifest.commands ?? {};
+    return task_agent_context_capabilities_1.TASK_AGENT_CONTEXT_COMMAND_IDS
+        .filter((commandId) => Boolean(commands[commandId]))
+        .map((commandId) => (0, task_agent_context_capabilities_1.taskAgentContextCommandCapability)(commandId));
+}
+/**
+ * The header is a UI compatibility declaration, never a permission claim.
+ * If the local manifest cannot be read we advertise nothing and let the
+ * server produce an explicit verification/update recovery state.
+ */
+function taskAgentContextRequestHeaders(rootDir) {
+    try {
+        const capabilities = taskAgentContextCapabilities((0, command_manifest_1.loadCommandManifest)(rootDir));
+        return capabilities.length > 0
+            ? { [exports.TASK_AGENT_CONTEXT_CAPABILITIES_HEADER]: capabilities.join(',') }
+            : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/lib/task-asset-upload.d.ts

@@ -24,6 +24,8 @@ export interface TaskAssetLedgerResource {
     expectationIds?: string[];
 }
 export interface UploadedTaskAsset {
+    /** Success is returned only after the server verifies the stored attachment. */
+    status: 'ready';
     /** The canonical Task relationship and exact Resource version recorded by this upload. */
     resourceReceipt?: TaskResourceWriteReceipt;
     id: string;
@@ -62,6 +64,8 @@ export declare function uploadTaskAssetFile(opts: {
     filePath: string;
     role?: TaskAssetRole;
     ledger?: TaskAssetLedgerResource;
+    /** Resume only this exact existing multipart attachment; never create a replacement intent. */
+    resumeAttachmentId?: string;
 }): Promise<UploadedTaskAsset>;
 /**
  * Upload every `--attach` file and return the reference objects an Update or
@@ -82,6 +86,24 @@ export declare function taskAssetMarkdownRef(asset: {
     id: string;
     filename: string;
 }): string;
+export type TaskAssetUploadRecovery = {
+    taskId: string;
+    attachmentId: string;
+    sessionId?: string;
+    transport: 'multipart';
+};
+/** A bounded recovery receipt, never a storage credential or claim that bytes are ready. */
+export declare function taskAssetUploadRecovery(error: unknown): TaskAssetUploadRecovery | undefined;
+/** PUT one bounded file range and report only the actual storage receipt and streamed bytes. */
+export declare function putFilePartToStorage(p: {
+    uploadUrl: string;
+    filePath: string;
+    offset: number;
+    byteLength: number;
+}): Promise<{
+    etag: string;
+    byteLength: number;
+}>;
 /** sha256 of a file, read as a stream: a 250MB recording never sits in memory. */
 export declare function sha256OfFile(filePath: string): Promise<string>;
 /**