@skrr-ai/cli 0.1.108 → 0.1.109

package/dist/lib/tasks.js

@@ -21,6 +21,8 @@ exports.applyProspectiveTaskExecutionMode = applyProspectiveTaskExecutionMode;
 exports.validateTaskCreateReferences = validateTaskCreateReferences;
 exports.resolveTaskCreateScope = resolveTaskCreateScope;
 exports.findTaskByExternalKey = findTaskByExternalKey;
+exports.externalKeyLookupId = externalKeyLookupId;
+exports.findTasksByExternalKeys = findTasksByExternalKeys;
 exports.droppedDefaultAssignees = droppedDefaultAssignees;
 exports.applyTaskAssigneeDefaults = applyTaskAssigneeDefaults;
 exports.hasExplicitTaskAssignee = hasExplicitTaskAssignee;
@@ -622,6 +624,136 @@ async function findTaskByExternalKey({ externalKey, spaceId, goalId, parentId, }
     }
     return { task: items[0] ?? null, duplicates: [] };
 }
+/** The identity of one lookup: a key means a task only within its scope. */
+function externalKeyLookupId(lookup) {
+    const scope = (value) => (typeof value === 'string' ? value : '');
+    return `${scope(lookup.spaceId)}|${scope(lookup.goalId)}|${lookup.externalKey}`;
+}
+function longestCommonPrefix(values) {
+    if (values.length === 0)
+        return '';
+    let prefix = values[0];
+    for (const value of values) {
+        let i = 0;
+        while (i < prefix.length && i < value.length && prefix[i] === value[i])
+            i += 1;
+        prefix = prefix.slice(0, i);
+        if (!prefix)
+            break;
+    }
+    return prefix;
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+/**
+ * Which of these tasks already exist? Answers for many keys at once.
+ *
+ * `create-tree`, `--resume` and `--verify` all start by asking that of every node
+ * of a tree, and asked it once per node, one after another: 94 round trips
+ * before the first write (OSK-S-440 #3). Two things bring that down without
+ * changing a single answer:
+ *
+ *   - Keys that share a prefix (`aap/c1`, `aap/c2`, ... — a tree is written
+ *     under one) are answered by ONE paged read of the prefix, per scope. The
+ *     read can return rows that are not this tree's; they are ignored, since a
+ *     key is matched whole. If the prefix is broad enough that the read hits its
+ *     page cap, whatever it did not find is looked up directly, because absence
+ *     from a truncated read proves nothing.
+ *   - Whatever is left is looked up by exact key, a few at a time rather than
+ *     one at a time.
+ *
+ * A server that predates `externalKeyPrefix` ignores it and returns the scope's
+ * tasks: still correct (matched whole), merely a wider read, and bounded by the
+ * same cap.
+ */
+async function findTasksByExternalKeys(lookups, opts = {}) {
+    const concurrency = opts.concurrency ?? 6;
+    const minKeysForPrefix = opts.minKeysForPrefix ?? 8;
+    const maxPages = opts.maxPages ?? 10;
+    const hits = new Map();
+    const unique = new Map();
+    for (const lookup of lookups)
+        unique.set(externalKeyLookupId(lookup), lookup);
+    const byScope = new Map();
+    for (const lookup of unique.values()) {
+        const scopeId = externalKeyLookupId({ ...lookup, externalKey: '' });
+        byScope.set(scopeId, [...(byScope.get(scopeId) ?? []), lookup]);
+    }
+    const settle = (lookup, rows) => {
+        const matching = rows.filter((row) => row.externalKey === lookup.externalKey);
+        hits.set(externalKeyLookupId(lookup), {
+            task: matching.length === 1 ? matching[0] : null,
+            duplicates: matching.length > 1 ? matching : [],
+        });
+    };
+    for (const group of byScope.values()) {
+        let unresolved = group;
+        const prefix = longestCommonPrefix(group.map((lookup) => lookup.externalKey));
+        if (group.length >= minKeysForPrefix && prefix.length >= 3) {
+            try {
+                const rows = [];
+                let cursor;
+                let complete = false;
+                for (let page = 0; page < maxPages; page += 1) {
+                    const response = (await data_provider_1.dataService.listTasks({
+                        externalKeyPrefix: prefix,
+                        ...(typeof group[0].spaceId === 'string' && group[0].spaceId
+                            ? { spaceId: group[0].spaceId }
+                            : {}),
+                        ...(typeof group[0].goalId === 'string' && group[0].goalId
+                            ? { goalId: group[0].goalId }
+                            : {}),
+                        limit: 200,
+                        ...(cursor ? { cursor } : {}),
+                    }));
+                    rows.push(...listItems(response));
+                    if (!response?.has_more || !response.next_cursor) {
+                        complete = true;
+                        break;
+                    }
+                    cursor = response.next_cursor;
+                }
+                unresolved = [];
+                for (const lookup of group) {
+                    const found = rows.some((row) => row.externalKey === lookup.externalKey);
+                    // Absence is only an answer from a read that reached the end.
+                    if (found || complete)
+                        settle(lookup, rows);
+                    else
+                        unresolved.push(lookup);
+                }
+            }
+            catch {
+                unresolved = group; // the prefix read failing is not an answer; look directly
+            }
+        }
+        await mapWithConcurrency(unresolved, concurrency, async (lookup) => {
+            try {
+                const { task, duplicates } = await findTaskByExternalKey(lookup);
+                hits.set(externalKeyLookupId(lookup), { task, duplicates });
+            }
+            catch (err) {
+                hits.set(externalKeyLookupId(lookup), {
+                    task: null,
+                    duplicates: [],
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+    }
+    return hits;
+}
 /**
  * Which DEFAULTED assignees the create route will strip because they are not
  * members of the task's space (`ASSIGNEE_NOT_IN_SPACE` degradation). Only a

package/dist/lib/triggers.d.ts

@@ -1,4 +1,4 @@
-import { type EmbeddedActionRef, type TriggerPreflightReport, type TriggerSensorConfig } from '@skrr-ai/data-provider';
+import { type EmbeddedActionRef, type TriggerIntentUnsupportedItem, type TriggerPreflightReport, type TriggerSensorConfig } from '@skrr-ai/data-provider';
 export declare const TRIGGER_KINDS: readonly ["schedule", "once", "event", "stochastic", "self_scheduled", "on_demand", "form", "chat_message"];
 export declare const TRIGGER_SCOPE_KINDS: readonly ["agent", "group_chat_subscriber", "space_oracle", "space_subscriber", "key_result_watcher", "task_watcher", "goal_watcher", "entity_reminder"];
 /**
@@ -160,6 +160,13 @@ export interface TriggerParseIntentResponse {
     message?: string;
     needsClarification?: boolean;
     proposedTrigger?: Record<string, unknown> | null;
+    /** Conditions the person asked for that the proposal does NOT apply (OSK-15402). */
+    unsupported?: TriggerIntentUnsupportedItem[];
+    /** The transcript including this turn; send it back with a reply to answer a question. */
+    history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
     usage?: Record<string, unknown>;
 }
 export interface TriggerEventCatalogEntry {
@@ -288,6 +295,29 @@ export declare const FLAG_OWNER_KINDS: Readonly<Record<string, readonly string[]
 export declare function assertKindFlagsApply(kind: unknown, flags: Record<string, unknown>, options?: {
     kindIsFixed?: boolean;
 }): void;
+/**
+ * The request body path each `triggers create` flag writes, for reading a server refusal back
+ * in the person's own words (`lib/request-field-flags.ts`). The server validates the body and
+ * names `execution.workflowSignal`; the person typed `--workflow-event-key` (OSK-15313). A path
+ * missing here is simply left as the server wrote it.
+ */
+export declare const TRIGGER_CREATE_FIELD_FLAGS: Readonly<Record<string, string>>;
+/**
+ * Flags an execution mode cannot work without, refused before the request is sent. The inverse
+ * case (`--workflow-outcome` without `--workflow-event-key`) was already refused by oclif's
+ * `dependsOn`; the missing key for `--mode workflow_signal` went to the server and came back
+ * naming an internal path (OSK-15313).
+ */
+export declare const TRIGGER_MODE_REQUIRED_FLAGS: Readonly<Record<string, ReadonlyArray<{
+    flag: string;
+    field: string;
+    why: string;
+}>>>;
+/**
+ * Refuse a mode whose required flag is missing, unless the body the person supplied
+ * (`--from-json`) already carries the field the flag would write.
+ */
+export declare function assertModeRequiredFlags(mode: unknown, flags: Record<string, unknown>, execution: Record<string, unknown> | undefined): void;
 /**
  * The sentence for a fire's `scheduledFire` report: what a MANUAL fire skipped that a scheduled
  * one would not. A manual fire is exempt from the enabled gate, the working/quiet-hours overlay and

package/dist/lib/triggers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.triggerApi = exports.AgentTriggerScopeError = exports.FLAG_OWNER_KINDS = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
+exports.triggerApi = exports.AgentTriggerScopeError = exports.TRIGGER_MODE_REQUIRED_FLAGS = exports.TRIGGER_CREATE_FIELD_FLAGS = exports.FLAG_OWNER_KINDS = exports.SCOPE_IMPLIED_REF_KEY = exports.TRIGGER_EVENT_CATALOG = exports.TRIGGER_EVENT_ENTITY_TYPES = exports.TRIGGER_CHAT_AUTH_MODES = exports.TRIGGER_CHAT_RESPONSE_MODES = exports.TRIGGER_CHAT_MODES = exports.TRIGGER_FORM_RESPONSE_MODES = exports.TRIGGER_CONCURRENCY_POLICIES = exports.TRIGGER_EVENT_FILTER_MODES = exports.TRIGGER_EXECUTOR_MODES = exports.TRIGGER_SCOPE_KINDS = exports.TRIGGER_KINDS = void 0;
 exports.validateEventReference = validateEventReference;
 exports.validateEventFilter = validateEventFilter;
 exports.serverEventCatalogIncludes = serverEventCatalogIncludes;
@@ -24,6 +24,7 @@ exports.setDefined = setDefined;
 exports.mergeObjectField = mergeObjectField;
 exports.mergeTriggerKindConfig = mergeTriggerKindConfig;
 exports.assertKindFlagsApply = assertKindFlagsApply;
+exports.assertModeRequiredFlags = assertModeRequiredFlags;
 exports.describeScheduledFire = describeScheduledFire;
 exports.fireWasAccepted = fireWasAccepted;
 exports.describeFireDetail = describeFireDetail;
@@ -746,6 +747,59 @@ function assertKindFlagsApply(kind, flags, options = {}) {
     }
     throw new Error(`${named.join(', ')} ${verb} not apply to ${subject}.${fix}`);
 }
+/**
+ * The request body path each `triggers create` flag writes, for reading a server refusal back
+ * in the person's own words (`lib/request-field-flags.ts`). The server validates the body and
+ * names `execution.workflowSignal`; the person typed `--workflow-event-key` (OSK-15313). A path
+ * missing here is simply left as the server wrote it.
+ */
+exports.TRIGGER_CREATE_FIELD_FLAGS = Object.freeze({
+    'execution.mode': '--mode',
+    'execution.promptTemplate': '--prompt',
+    'execution.conversationId': '--conversation',
+    'execution.builtinAction': '--builtin-action',
+    'execution.effectPolicy': '--effect-contract',
+    'execution.effectPolicy.contract': '--effect-contract',
+    'execution.effectPolicy.writeMode': '--effect-write-mode',
+    'execution.effectPolicy.options': '--effect-options',
+    // The whole block is written by --workflow-event-key: without it the block is not sent.
+    'execution.workflowSignal': '--workflow-event-key',
+    'execution.workflowSignal.eventKey': '--workflow-event-key',
+    'execution.workflowSignal.outcome': '--workflow-outcome',
+    'execution.dispatch': '--dispatch',
+    'execution.references': '--reference',
+    'execution.workingHours': '--working-hours',
+    'execution.quietHours': '--quiet-hours',
+});
+/**
+ * Flags an execution mode cannot work without, refused before the request is sent. The inverse
+ * case (`--workflow-outcome` without `--workflow-event-key`) was already refused by oclif's
+ * `dependsOn`; the missing key for `--mode workflow_signal` went to the server and came back
+ * naming an internal path (OSK-15313).
+ */
+exports.TRIGGER_MODE_REQUIRED_FLAGS = Object.freeze({
+    workflow_signal: [
+        {
+            flag: 'workflow-event-key',
+            field: 'workflowSignal',
+            why: 'the exact event key the parked workflow step waits on',
+        },
+    ],
+});
+/**
+ * Refuse a mode whose required flag is missing, unless the body the person supplied
+ * (`--from-json`) already carries the field the flag would write.
+ */
+function assertModeRequiredFlags(mode, flags, execution) {
+    if (typeof mode !== 'string')
+        return;
+    const missing = (exports.TRIGGER_MODE_REQUIRED_FLAGS[mode] ?? []).filter((requirement) => !flagWasPassed(flags[requirement.flag]) && execution?.[requirement.field] === undefined);
+    if (missing.length === 0)
+        return;
+    throw new Error(missing
+        .map((requirement) => `--mode ${mode} requires --${requirement.flag}: ${requirement.why}.`)
+        .join(' '));
+}
 /**
  * The sentence for a fire's `scheduledFire` report: what a MANUAL fire skipped that a scheduled
  * one would not. A manual fire is exempt from the enabled gate, the working/quiet-hours overlay and

package/dist/lib/workflow-issues.d.ts

@@ -0,0 +1,14 @@
+import type { WorkflowIssue } from '@skrr-ai/data-provider';
+/**
+ * Lines that say what in a workflow draft is wrong, and where.
+ *
+ * A draft may be STORED invalid — the canvas saves while you are still building
+ * — so `create` and `update` succeed on a graph `publish` will refuse. They used
+ * to print a bare success, and the author learned at publish (OSK-15328). The
+ * server now returns the shared linter's `issues` on every write and on
+ * validate; this renders them the same way on all three, each naming its node
+ * and field so it can be acted on without reading the graph again.
+ */
+export declare function formatWorkflowIssues(issues: WorkflowIssue[] | undefined): string[];
+/** The heading plus issue lines for a draft write, or nothing when the draft is clean. */
+export declare function describeDraftIssues(issues: WorkflowIssue[] | undefined): string[];

package/dist/lib/workflow-issues.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWorkflowIssues = formatWorkflowIssues;
+exports.describeDraftIssues = describeDraftIssues;
+/**
+ * Lines that say what in a workflow draft is wrong, and where.
+ *
+ * A draft may be STORED invalid — the canvas saves while you are still building
+ * — so `create` and `update` succeed on a graph `publish` will refuse. They used
+ * to print a bare success, and the author learned at publish (OSK-15328). The
+ * server now returns the shared linter's `issues` on every write and on
+ * validate; this renders them the same way on all three, each naming its node
+ * and field so it can be acted on without reading the graph again.
+ */
+function formatWorkflowIssues(issues) {
+    return (issues ?? []).map((issue) => {
+        const where = [issue.nodeKey, issue.path].filter(Boolean).join(' ');
+        const label = issue.severity === 'error' ? 'error' : 'warning';
+        return `  ${label}${where ? ` [${where}]` : ''}: ${issue.message}`;
+    });
+}
+/** The heading plus issue lines for a draft write, or nothing when the draft is clean. */
+function describeDraftIssues(issues) {
+    const list = issues ?? [];
+    if (!list.length)
+        return [];
+    const errors = list.filter((issue) => issue.severity === 'error').length;
+    const heading = errors
+        ? `Saved, but this draft cannot be published yet (${errors} error${errors === 1 ? '' : 's'}):`
+        : `Saved. ${list.length} warning${list.length === 1 ? '' : 's'} (publishing is allowed):`;
+    return [heading, ...formatWorkflowIssues(list)];
+}

package/dist/lib/workflow-run-view.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What the plain-text workflow run view says about each node beyond its status.
+ *
+ * The table showed key/type/status/task, so three facts the server already knew were visible
+ * only under `--json` (OSK-15325): a loop that `succeeded` while one of its items failed, what a
+ * `waiting` node was waiting FOR (an event key, an approval, a child run), and how to resolve a
+ * wait a signal can resolve. Rows were also in node-creation order rather than graph order.
+ * Everything here reads server-derived fields (`depth`, `loopSummary`, `signalable`, `waitKind`)
+ * and recomputes none of them.
+ */
+export interface RunViewNode {
+    nodeKey?: unknown;
+    nodeType?: unknown;
+    status?: unknown;
+    depth?: unknown;
+    lane?: unknown;
+    attentionReason?: unknown;
+    error?: {
+        message?: unknown;
+    } | null;
+    waitKind?: unknown;
+    signalable?: unknown;
+    waitingFor?: unknown;
+    loopSummary?: {
+        total?: unknown;
+        completed?: unknown;
+        succeeded?: unknown;
+        failed?: unknown;
+        partial?: unknown;
+        settled?: unknown;
+    } | null;
+}
+/** One printable line: control characters (an ESC sequence included) become spaces. */
+export declare function printable(value: string): string;
+/**
+ * Nodes in graph order: the server's topological `depth` first, then the order the server
+ * returned them in (a stable sort), so siblings at one depth keep their relative order.
+ */
+export declare function orderNodesByGraph<T extends RunViewNode>(nodes: readonly T[]): T[];
+/** "2 of 3 items succeeded, 1 failed" for a loop, or '' when the server sent no summary. */
+export declare function describeLoopProgress(node: RunViewNode): string;
+/** The DETAIL cell: what needs eyes, what a wait waits for, and how far a loop got. */
+export declare function describeNodeDetail(node: RunViewNode, attention?: string): string;
+/**
+ * How to resolve each wait a signal can resolve. Only the server's `signalable` decides: a loop
+ * or child-run wait is settled by its work, and offering a command for it would invite a person
+ * to skip that work.
+ */
+export declare function describeSignalHints(spaceId: string, runId: string, nodes: readonly RunViewNode[], bin?: string): string[];
+/**
+ * Lines a run's headline status cannot carry: a node that succeeded although some of its items
+ * failed. A loop under `onItemFailure: continue` with a permissive join succeeds with a failed
+ * item, so "run succeeded" alone hid the failure.
+ */
+export declare function describePartialOutcomes(nodes: readonly RunViewNode[]): string[];

package/dist/lib/workflow-run-view.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printable = printable;
+exports.orderNodesByGraph = orderNodesByGraph;
+exports.describeLoopProgress = describeLoopProgress;
+exports.describeNodeDetail = describeNodeDetail;
+exports.describeSignalHints = describeSignalHints;
+exports.describePartialOutcomes = describePartialOutcomes;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const format_1 = require("./format");
+/** One printable line: control characters (an ESC sequence included) become spaces. */
+function printable(value) {
+    // eslint-disable-next-line no-control-regex
+    return (0, format_1.collapseWhitespace)(value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
+}
+/**
+ * Nodes in graph order: the server's topological `depth` first, then the order the server
+ * returned them in (a stable sort), so siblings at one depth keep their relative order.
+ */
+function orderNodesByGraph(nodes) {
+    const depthOf = (node) => typeof node.depth === 'number' && Number.isFinite(node.depth)
+        ? node.depth
+        : Number.MAX_SAFE_INTEGER;
+    return nodes
+        .map((node, index) => ({ node, index }))
+        .sort((a, b) => depthOf(a.node) - depthOf(b.node) || a.index - b.index)
+        .map((entry) => entry.node);
+}
+/** "2 of 3 items succeeded, 1 failed" for a loop, or '' when the server sent no summary. */
+function describeLoopProgress(node) {
+    const summary = node.loopSummary;
+    if (node.nodeType !== 'loop' || !summary)
+        return '';
+    const total = Number(summary.total);
+    const completed = Number(summary.completed);
+    const succeeded = Number(summary.succeeded);
+    const failed = Number(summary.failed);
+    if (![total, completed, succeeded, failed].every(Number.isFinite))
+        return '';
+    const parts = [`${succeeded} of ${total} item${total === 1 ? '' : 's'} succeeded`];
+    if (failed > 0)
+        parts.push(`${failed} failed`);
+    if (summary.settled === true && completed < total)
+        parts.push(`${total - completed} not run`);
+    return parts.join(', ');
+}
+/** The DETAIL cell: what needs eyes, what a wait waits for, and how far a loop got. */
+function describeNodeDetail(node, attention = '') {
+    const parts = [];
+    const wait = (0, data_provider_1.describeWorkflowNodeWait)(node);
+    // "approval; waiting for an approval" says one thing twice: the wait phrase carries it.
+    if (attention && attention !== wait?.kind)
+        parts.push(attention);
+    if (wait)
+        parts.push(wait.text);
+    const loop = describeLoopProgress(node);
+    if (loop)
+        parts.push(loop);
+    return printable(parts.join('; '));
+}
+/**
+ * How to resolve each wait a signal can resolve. Only the server's `signalable` decides: a loop
+ * or child-run wait is settled by its work, and offering a command for it would invite a person
+ * to skip that work.
+ */
+function describeSignalHints(spaceId, runId, nodes, bin = 'skrr') {
+    const lines = [];
+    for (const node of nodes) {
+        if (node.status !== 'waiting' || node.signalable !== true)
+            continue;
+        const key = printable(String(node.nodeKey ?? ''));
+        if (!key)
+            continue;
+        const wait = (0, data_provider_1.describeWorkflowNodeWait)(node);
+        const what = wait?.kind === 'approval' ? 'approve or reject it' : 'resolve it by hand';
+        lines.push(`To ${what}: ${bin} spaces workflows signal ${spaceId} ${runId} ${key}` +
+            (wait?.kind === 'approval'
+                ? ' [--outcome failure]'
+                : ' [--outcome failure] [--payload <json>]'));
+    }
+    return lines;
+}
+/**
+ * Lines a run's headline status cannot carry: a node that succeeded although some of its items
+ * failed. A loop under `onItemFailure: continue` with a permissive join succeeds with a failed
+ * item, so "run succeeded" alone hid the failure.
+ */
+function describePartialOutcomes(nodes) {
+    const lines = [];
+    for (const node of nodes) {
+        const summary = node.loopSummary;
+        // A failed loop already says so in its STATUS column; only a success can hide one.
+        if (node.nodeType !== 'loop' || node.status !== 'succeeded')
+            continue;
+        if (!summary || summary.partial !== true)
+            continue;
+        const failed = Number(summary.failed);
+        const total = Number(summary.total);
+        if (!Number.isFinite(failed) || failed <= 0)
+            continue;
+        lines.push(`Note: ${printable(String(node.nodeKey ?? 'loop'))} succeeded, but ` +
+            `${failed} of ${Number.isFinite(total) ? total : '?'} item${total === 1 ? '' : 's'} failed.`);
+    }
+    return lines;
+}

package/dist/lib/workspaces.d.ts

@@ -12,11 +12,8 @@ export interface StewardshipCoverage {
     truncated: boolean;
     sources: StewardshipSource[];
 }
-export type WorkspaceGrantMetadata = Omit<GrantPublic, 'credential' | 'createdAt' | 'updatedAt'> & {
+export type WorkspaceGrantMetadata = Omit<GrantPublic, 'createdAt' | 'updatedAt'> & {
     ownerUserId: string;
-    credential: (NonNullable<GrantPublic['credential']> & {
-        fingerprint?: string;
-    }) | null;
     createdAt?: string;
     updatedAt?: string;
     referencedBy: string[] | null;
@@ -47,6 +44,36 @@ export interface WorkspaceStewardshipReport extends WorkspaceGrantReport {
     }> | null;
 }
 export declare function getWorkspaceStewardship(workspaceId: string, memberUserId: string): Promise<WorkspaceStewardshipReport>;
+/** One current member of a workspace, as `GET /api/workspaces/:id/members` returns it. */
+export interface WorkspaceMemberRow {
+    userId: string;
+    role: string;
+    joinedAt?: string;
+    user?: {
+        _id?: string;
+        name?: string;
+        username?: string;
+        email?: string;
+    };
+}
+export declare function listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMemberRow[]>;
+/** A user id as the stewardship route takes it: a 24-hex ObjectId. */
+export declare const USER_ID_PATTERN: RegExp;
+export declare class MemberReferenceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Turn what a person typed into the member's user id (OSK-15356).
+ *
+ * A 24-hex id is passed through untouched: the server answers for it, including
+ * for an id that is not (or is no longer) a member. An email is looked up among
+ * the workspace's CURRENT members, because that is the only directory this
+ * command may read; a former member's email therefore does not resolve, and the
+ * error says so instead of guessing. Anything else is refused here with the
+ * shapes that work, rather than sent to the server for a bare "valid user id
+ * is required".
+ */
+export declare function resolveMemberUserId(workspaceId: string, reference: string, list?: (workspaceId: string) => Promise<WorkspaceMemberRow[]>): Promise<string>;
 export declare function listWorkspaceGrants(workspaceId: string): Promise<WorkspaceGrantReport>;
 /**
  * The workspaces this account belongs to.

package/dist/lib/workspaces.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemberReferenceError = exports.USER_ID_PATTERN = void 0;
 exports.getWorkspaceStewardship = getWorkspaceStewardship;
+exports.listWorkspaceMembers = listWorkspaceMembers;
+exports.resolveMemberUserId = resolveMemberUserId;
 exports.listWorkspaceGrants = listWorkspaceGrants;
 exports.describeUnselectedWorkspace = describeUnselectedWorkspace;
 exports.listWorkspaces = listWorkspaces;
@@ -15,6 +18,46 @@ const triggers_1 = require("./triggers");
 async function getWorkspaceStewardship(workspaceId, memberUserId) {
     return (0, api_fetch_1.apiFetch)(`/api/workspaces/${encodeURIComponent(workspaceId)}/stewardship/members/${encodeURIComponent(memberUserId)}`);
 }
+async function listWorkspaceMembers(workspaceId) {
+    const response = await (0, api_fetch_1.apiFetch)(`/api/workspaces/${encodeURIComponent(workspaceId)}/members`);
+    return Array.isArray(response?.data) ? response.data : [];
+}
+/** A user id as the stewardship route takes it: a 24-hex ObjectId. */
+exports.USER_ID_PATTERN = /^[a-f0-9]{24}$/i;
+class MemberReferenceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MemberReferenceError';
+    }
+}
+exports.MemberReferenceError = MemberReferenceError;
+/**
+ * Turn what a person typed into the member's user id (OSK-15356).
+ *
+ * A 24-hex id is passed through untouched: the server answers for it, including
+ * for an id that is not (or is no longer) a member. An email is looked up among
+ * the workspace's CURRENT members, because that is the only directory this
+ * command may read; a former member's email therefore does not resolve, and the
+ * error says so instead of guessing. Anything else is refused here with the
+ * shapes that work, rather than sent to the server for a bare "valid user id
+ * is required".
+ */
+async function resolveMemberUserId(workspaceId, reference, list = listWorkspaceMembers) {
+    const value = reference.trim();
+    if (exports.USER_ID_PATTERN.test(value))
+        return value;
+    const listHint = `\`skrr workspaces members ${workspaceId}\` lists current members and their user ids.`;
+    if (!value.includes('@')) {
+        throw new MemberReferenceError(`"${reference}" is not a user id or an email. A user id is 24 hexadecimal characters. ${listHint}`);
+    }
+    const email = value.toLowerCase();
+    const matches = (await list(workspaceId)).filter((member) => member.user?.email?.toLowerCase() === email);
+    if (matches.length === 1)
+        return String(matches[0].userId);
+    throw new MemberReferenceError(matches.length === 0
+        ? `No current member of this workspace has the email ${value}. A former member's email cannot be looked up here; use their user id. ${listHint}`
+        : `More than one member has the email ${value}; use the user id. ${listHint}`);
+}
 async function listWorkspaceGrants(workspaceId) {
     return (0, api_fetch_1.apiFetch)(`/api/workspaces/${encodeURIComponent(workspaceId)}/stewardship/grants`);
 }

package/dist/lib/write-target.d.ts

@@ -0,0 +1,29 @@
+export type WriteTarget = {
+    /** The API origin writes go to, e.g. `https://skrr.ai`. */
+    server: string;
+    /** The signed-in account's email, or null when it could not be read. */
+    account: string | null;
+    accountId: string | null;
+    /** The workspace the request is scoped to, or null for none. */
+    workspace: string | null;
+};
+/** `stevedu518@gmail.com on https://skrr.ai (no workspace)` */
+export declare function formatWriteTarget(target: WriteTarget): string;
+/**
+ * Does one `--expect-target` value describe this target?
+ *
+ *   - contains `@`            -> the account email (case-insensitive)
+ *   - a URL or a host name    -> the server's host (`skrr.ai` matches `https://skrr.ai`)
+ *   - anything else           -> the account id
+ *
+ * One value names one fact; pass the flag twice to pin both account and server.
+ * An unreadable fact never matches: an expectation about an account the command
+ * could not read is not met.
+ */
+export declare function matchesExpectedTarget(target: WriteTarget, expected: string): boolean;
+/** The first expectation that does NOT hold, or undefined when all do. */
+export declare function firstUnmetExpectation(target: WriteTarget, expected: readonly string[] | undefined): string | undefined;
+/** The assertion flag, declared once so every bulk writer spells it the same way. */
+export declare const expectTargetFlag: {
+    'expect-target': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+};