@skrr-ai/cli 0.1.8

package/dist/lib/tasks.js

@@ -0,0 +1,714 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_WORK_EVENT_KINDS = void 0;
+exports.releasePinRepairGuard = releasePinRepairGuard;
+exports.taskUpdateMutationGuard = taskUpdateMutationGuard;
+exports.executionIsolationFromWorktreeFlag = executionIsolationFromWorktreeFlag;
+exports.buildTaskCreatePayload = buildTaskCreatePayload;
+exports.boundSessionAgentId = boundSessionAgentId;
+exports.applyDaemonSessionDefaults = applyDaemonSessionDefaults;
+exports.validateTaskCreatePayload = validateTaskCreatePayload;
+exports.applyInferredTaskExecutionMode = applyInferredTaskExecutionMode;
+exports.applyProspectiveTaskExecutionMode = applyProspectiveTaskExecutionMode;
+exports.validateTaskCreateReferences = validateTaskCreateReferences;
+exports.resolveTaskCreateScope = resolveTaskCreateScope;
+exports.findTaskByExternalKey = findTaskByExternalKey;
+exports.droppedDefaultAssignees = droppedDefaultAssignees;
+exports.applyTaskAssigneeDefaults = applyTaskAssigneeDefaults;
+exports.hasExplicitTaskAssignee = hasExplicitTaskAssignee;
+exports.implicitTaskDefaultAgentMode = implicitTaskDefaultAgentMode;
+exports.applyDefaultAgentToPayload = applyDefaultAgentToPayload;
+exports.createPatchFromCreatePayload = createPatchFromCreatePayload;
+exports.removeUndefinedFields = removeUndefinedFields;
+exports.listItems = listItems;
+exports.taskId = taskId;
+exports.taskRef = taskRef;
+exports.formatTaskLabel = formatTaskLabel;
+exports.hasTaskAssignee = hasTaskAssignee;
+exports.normalizeTaskUpdateEntry = normalizeTaskUpdateEntry;
+exports.normalizeBulkUpdateInput = normalizeBulkUpdateInput;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const prompt_1 = require("./prompt");
+const projects_1 = require("./projects");
+const TASK_PRIORITIES = ['low', 'medium', 'high', 'critical'];
+const DESCRIPTION_FORMATS = ['html', 'markdown', 'plain'];
+/**
+ * The kinds `tasks events append --kind` will accept.
+ *
+ * A SECOND DECLARATION of a server-owned vocabulary — the authority is
+ * `TASK_WORK_EVENT_KINDS` in `packages/data-schemas/src/schema/taskWorkEvent.ts`,
+ * which the server validates against (`TaskWorkEvent.js` → `KINDS.has(kind)`).
+ * The CLI does not depend on `data-schemas` (it pulls mongoose), so the copy
+ * stays and `__tests__/task-work-event-kind-parity.spec.ts` pins it against the
+ * source — turning a silently rejected `--kind` into a build failure instead.
+ * Without the `options` list a bad value came back only as the server's generic
+ * `Invalid request data` / HTTP_400, naming neither the field nor the choices.
+ */
+exports.TASK_WORK_EVENT_KINDS = [
+    'started',
+    'checkpoint',
+    'changed',
+    'evidence',
+    'decision',
+    'blocker',
+    'input_requested',
+    'handoff',
+    'verification',
+    'completed',
+    'failed',
+    'lifecycle',
+];
+const AGENT_ASSIGNEE_MUTATION_FIELDS = [
+    'assigneeAgentIds',
+    'addAssigneeAgentIds',
+    'removeAssigneeAgentIds',
+];
+/**
+ * Release-pin repair is a mutation option, not a standalone operation. If no
+ * agent-assignee field is present the server has no continuity transition to
+ * run, so accepting the option would be a successful no-op.
+ */
+function releasePinRepairGuard(payload) {
+    if (payload.repairReleasePins !== true)
+        return null;
+    const changesAgentAssignees = AGENT_ASSIGNEE_MUTATION_FIELDS.some((field) => Object.prototype.hasOwnProperty.call(payload, field));
+    if (changesAgentAssignees)
+        return null;
+    return {
+        code: 'REPAIR_WITHOUT_ASSIGNEE_CHANGE',
+        message: '--repair-release-pins repairs pins as part of an agent-assignee change; pass it ' +
+            'alongside --assignee-agent / --add-assignee-agent / --remove-assignee-agent.',
+    };
+}
+/**
+ * Guard the single-task `tasks update` surface. JSON input is intentionally
+ * open-ended, so the absence of a typed `--status` flag alone does not prevent
+ * callers from bypassing the canonical move endpoint.
+ */
+function taskUpdateMutationGuard(payload) {
+    if (Object.prototype.hasOwnProperty.call(payload, 'status')) {
+        return {
+            code: 'TASK_STATUS_REQUIRES_MOVE',
+            message: '`tasks update` does not change status. Use `skrr tasks move <task-id> --status <status>` ' +
+                '(or `tasks bulk-update`, which routes status through the move endpoint).',
+        };
+    }
+    return releasePinRepairGuard(payload);
+}
+/**
+ * Map the tri-state `--worktree` flag to the `executionIsolation` value.
+ * true ⇒ 'ephemeral', false ⇒ 'shared', undefined ⇒ undefined (inherit/leave).
+ */
+function executionIsolationFromWorktreeFlag(worktree) {
+    if (worktree === undefined)
+        return undefined;
+    return worktree ? 'ephemeral' : 'shared';
+}
+function buildTaskCreatePayload(body, flags = {}) {
+    const payload = (0, prompt_1.mergeDefined)(body, {
+        templateId: flags.template,
+        title: flags.title,
+        description: flags.description,
+        descriptionFormat: flags['description-format'],
+        externalKey: flags['external-key'],
+        priority: flags.priority,
+        parentId: flags.parent,
+        spaceId: flags.space,
+        goalId: flags.goal,
+        commitmentId: flags.commitment,
+        projectId: flags.project,
+        cycleId: flags.cycle,
+        assigneeAgentIds: flags['assignee-agent'],
+        assigneeUserIds: flags['assignee-user'],
+        executionMode: flags['execution-mode'],
+        startDate: flags['start-date'],
+        dueDate: flags['due-date'],
+        estimate: flags.estimate,
+        tags: flags.tag,
+        labelIds: flags['label-id'],
+        sourceConversationId: flags['source-conversation'],
+        sourceMessageId: flags['source-message'],
+        // Lineage — which work produced this work. Kept beside the source-*
+        // provenance fields because it answers the same class of question, but it
+        // is a Task→Task edge rather than a pointer at a chat message.
+        spawnedByTaskId: flags['spawned-by'],
+        spawnReason: flags['spawn-reason'],
+        // Worktree isolation opt-in. --worktree ⇒ 'ephemeral', --no-worktree ⇒
+        // 'shared', omitted ⇒ undefined (inherit space policy / global default).
+        executionIsolation: executionIsolationFromWorktreeFlag(flags.worktree),
+    });
+    applyDaemonSessionDefaults(payload);
+    normalizeStringField(payload, 'externalKey', 300);
+    return payload;
+}
+/**
+ * The Agent this CLI process is running AS, if any.
+ *
+ * Read ONLY from the session environment the daemon injects when it spawns a
+ * harness. There is deliberately no fallback that asks the server "which agents
+ * does this account own" — that question cannot identify the caller, and the
+ * answer it used to give was either a hard failure (two agents) or a confident
+ * wrong assignment (one agent that had nothing to do with this session).
+ *
+ * An empty result means "this caller is not running as an agent", which is a
+ * fact about the session, not a problem to solve.
+ */
+function boundSessionAgentId() {
+    return envFirst('OVERSKY_SESSION_AGENT_ID', 'OVERSKY_AGENT_ID');
+}
+function applyDaemonSessionDefaults(payload) {
+    // Assignee defaulting deliberately does NOT happen here. It is one decision
+    // shared with the REST route and the MCP tools, and it needs the resolved
+    // `executionMode` — see `applyTaskAssigneeDefaults` below.
+    if (!Object.prototype.hasOwnProperty.call(payload, 'spaceId')) {
+        const spaceId = envFirst('OVERSKY_SESSION_SPACE_ID', 'OVERSKY_SPACE_ID');
+        if (spaceId)
+            payload.spaceId = spaceId;
+    }
+    // A commitment-owned agent run can create work that does not belong to a
+    // Goal. Preserve that durable ownership edge so later checks can observe the
+    // task rather than inferring it from its title, creator, or GitHub SHA.
+    if (!Object.prototype.hasOwnProperty.call(payload, 'commitmentId')) {
+        const commitmentId = envFirst('OVERSKY_SESSION_COMMITMENT_ID', 'OVERSKY_COMMITMENT_ID');
+        if (commitmentId)
+            payload.commitmentId = commitmentId;
+    }
+    if (!Object.prototype.hasOwnProperty.call(payload, 'sourceConversationId')) {
+        const conversationId = envFirst('OVERSKY_SESSION_CONVERSATION_ID', 'OVERSKY_CONVERSATION_ID');
+        if (conversationId)
+            payload.sourceConversationId = conversationId;
+    }
+    if (!Object.prototype.hasOwnProperty.call(payload, 'sourceMessageId') &&
+        typeof payload.sourceConversationId === 'string') {
+        const messageId = envFirst('OVERSKY_SESSION_SOURCE_MESSAGE_ID', 'OVERSKY_SOURCE_MESSAGE_ID');
+        if (messageId)
+            payload.sourceMessageId = messageId;
+    }
+}
+function validateTaskCreatePayload(payload) {
+    const errors = [];
+    if (!isNonEmptyString(payload.title) && !isNonEmptyString(payload.templateId)) {
+        errors.push('title is required and must be a non-empty string');
+    }
+    else if (String(payload.title).length > 200) {
+        errors.push('title must be at most 200 characters');
+    }
+    if (payload.description !== undefined && String(payload.description).length > 50000) {
+        errors.push('description must be at most 50000 characters');
+    }
+    if (payload.descriptionFormat !== undefined &&
+        !DESCRIPTION_FORMATS.includes(payload.descriptionFormat)) {
+        errors.push(`descriptionFormat must be one of: ${DESCRIPTION_FORMATS.join(', ')}`);
+    }
+    if (payload.priority !== undefined &&
+        !TASK_PRIORITIES.includes(payload.priority)) {
+        errors.push(`priority must be one of: ${TASK_PRIORITIES.join(', ')}`);
+    }
+    if (payload.externalKey !== undefined && !isBoundedString(payload.externalKey, 1, 300)) {
+        errors.push('externalKey must be a non-empty string at most 300 characters');
+    }
+    if (payload.templateId !== undefined && !isBoundedString(payload.templateId, 1, 100)) {
+        errors.push('templateId must be a non-empty string at most 100 characters');
+    }
+    for (const field of [
+        'parentId',
+        'goalId',
+        'commitmentId',
+        'spaceId',
+        'sourceConversationId',
+        'sourceMessageId',
+    ]) {
+        if (payload[field] !== undefined && !isNonEmptyString(payload[field])) {
+            errors.push(`${field} must be a non-empty string when provided`);
+        }
+    }
+    if (payload.sourceMessageId && !payload.sourceConversationId) {
+        errors.push('sourceMessageId requires sourceConversationId');
+    }
+    for (const field of ['tags', 'assigneeAgentIds', 'assigneeUserIds']) {
+        if (payload[field] !== undefined && !isStringArray(payload[field])) {
+            errors.push(`${field} must be an array of strings`);
+        }
+    }
+    const agentIds = stringArray(payload.assigneeAgentIds);
+    const userIds = stringArray(payload.assigneeUserIds);
+    if (payload.executionMode !== undefined &&
+        !data_provider_1.TASK_EXECUTION_MODES.includes(payload.executionMode)) {
+        errors.push(`executionMode must be one of: ${data_provider_1.TASK_EXECUTION_MODES.join(', ')}`);
+    }
+    else if (payload.executionMode === 'agent' && agentIds.length === 0) {
+        errors.push('executionMode=agent requires at least one Agent assignee');
+    }
+    else if (payload.executionMode === 'human' && userIds.length === 0) {
+        errors.push('executionMode=human requires at least one Human assignee');
+    }
+    else if (!payload.executionMode && agentIds.length > 0 && userIds.length > 0) {
+        errors.push('mixed Human and Agent assignees require --execution-mode agent|human');
+    }
+    if (Array.isArray(payload.tags) && payload.tags.length > 50) {
+        errors.push('tags should contain at most 50 entries');
+    }
+    if (payload.startDate !== undefined && Number.isNaN(Date.parse(String(payload.startDate)))) {
+        errors.push('startDate must be parseable as an ISO date/time string');
+    }
+    if (payload.dueDate !== undefined && Number.isNaN(Date.parse(String(payload.dueDate)))) {
+        errors.push('dueDate must be parseable as an ISO date/time string');
+    }
+    if (payload.startDate !== undefined &&
+        payload.dueDate !== undefined &&
+        !Number.isNaN(Date.parse(String(payload.startDate))) &&
+        !Number.isNaN(Date.parse(String(payload.dueDate))) &&
+        Date.parse(String(payload.startDate)) > Date.parse(String(payload.dueDate))) {
+        errors.push('startDate must be on or before dueDate');
+    }
+    return errors;
+}
+/** Stamp the unambiguous executor so CLI-authored tasks are explicit on day one. */
+function applyInferredTaskExecutionMode(payload) {
+    applyProspectiveTaskExecutionMode(payload);
+}
+/**
+ * Stamp an executor only when the post-update assignee set is unambiguous.
+ * Existing fields participate when an upsert omits one assignee kind; this
+ * prevents an Agent-only patch from silently deciding an already-Human task.
+ */
+function applyProspectiveTaskExecutionMode(payload, existingTask) {
+    if (payload.executionMode !== undefined)
+        return;
+    if (existingTask?.executionMode !== undefined)
+        return;
+    const agentIds = Object.prototype.hasOwnProperty.call(payload, 'assigneeAgentIds')
+        ? payload.assigneeAgentIds
+        : existingTask?.assigneeAgentIds;
+    const userIds = Object.prototype.hasOwnProperty.call(payload, 'assigneeUserIds')
+        ? payload.assigneeUserIds
+        : existingTask?.assigneeUserIds;
+    const hasAgents = stringArray(agentIds).length > 0;
+    const hasUsers = stringArray(userIds).length > 0;
+    if (hasAgents !== hasUsers)
+        payload.executionMode = hasAgents ? 'agent' : 'human';
+}
+async function validateTaskCreateReferences(payload) {
+    const errors = [];
+    if (isNonEmptyString(payload.parentId)) {
+        try {
+            await data_provider_1.dataService.getTask(String(payload.parentId), { enrich: false });
+        }
+        catch (err) {
+            errors.push(`parentId ${payload.parentId} is not accessible: ${formatApiError(err)}`);
+        }
+    }
+    if (isNonEmptyString(payload.spaceId)) {
+        try {
+            await data_provider_1.dataService.getSpace(String(payload.spaceId));
+        }
+        catch (err) {
+            errors.push(`spaceId ${payload.spaceId} is not accessible: ${formatApiError(err)}`);
+        }
+    }
+    return errors;
+}
+/**
+ * Resolve containment that contributes an inherited Space before assignee
+ * defaults run. The REST route performs the same Project inheritance, but
+ * waiting until after the request is too late for the CLI to choose the Space
+ * lead or resolve member names safely.
+ */
+async function resolveTaskCreateScope(payload, opts = {}) {
+    const resolution = {};
+    const parentId = stringValue(payload.parentId);
+    if (parentId) {
+        const parentTask = await getCachedTask(parentId, opts.parentTaskCache);
+        resolution.parentTask = parentTask;
+        const parentSpaceId = stringValue(parentTask.spaceId);
+        if (!stringValue(payload.spaceId) && parentSpaceId)
+            payload.spaceId = parentSpaceId;
+    }
+    const projectId = stringValue(payload.projectId);
+    if (projectId && !stringValue(payload.spaceId)) {
+        const project = await getCachedProject(projectId, opts.projectCache);
+        resolution.project = project;
+        const projectSpaceId = stringValue(project.spaceId);
+        if (!projectSpaceId) {
+            throw new Error(`Project ${projectId} did not return an owning space`);
+        }
+        payload.spaceId = projectSpaceId;
+    }
+    return resolution;
+}
+async function findTaskByExternalKey({ externalKey, spaceId, goalId, parentId, }) {
+    const response = await data_provider_1.dataService.listTasks({
+        externalKey,
+        ...(typeof spaceId === 'string' && spaceId ? { spaceId } : {}),
+        ...(typeof goalId === 'string' && goalId ? { goalId } : {}),
+        ...(typeof parentId === 'string' && parentId ? { parentId } : {}),
+        limit: 2,
+    });
+    const items = listItems(response);
+    if (items.length > 1) {
+        return { task: null, duplicates: items };
+    }
+    return { task: items[0] ?? null, duplicates: [] };
+}
+/**
+ * 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
+ * defaulted assignee is at risk here: an assignee the caller named explicitly
+ * is resolved against space membership up front and fails loudly, so it never
+ * reaches a `--dry-run` that "passed". A dry run that echoes such an assignee
+ * implies one the real create drops, which is what this predicts. (OSK-4857)
+ */
+function droppedDefaultAssignees(resolution, memberIds) {
+    if (!resolution.applied)
+        return { agentIds: [], userIds: [] };
+    return {
+        agentIds: (resolution.agentIds ?? []).filter((id) => !memberIds.has(id)),
+        userIds: (resolution.userIds ?? []).filter((id) => !memberIds.has(id)),
+    };
+}
+/**
+ * Apply the shared assignee-default policy to a create payload, in place.
+ *
+ * The CLI contributes only the CLAIM — did the caller assign anyone, what
+ * executor did they declare, and which agent (if any) does this session's
+ * environment say this process is. The DECISION lives in
+ * `resolveTaskAssigneeDefaults` (`@skrr-ai/data-provider`) so `skrr`, the REST
+ * route and the `task_create` MCP tool cannot answer it differently.
+ */
+function applyTaskAssigneeDefaults(payload, opts = {}) {
+    const resolution = (0, data_provider_1.resolveTaskAssigneeDefaults)({
+        hasExplicitAssignee: hasExplicitTaskAssignee(payload),
+        executionMode: payload.executionMode,
+        callerAgentId: boundSessionAgentId(),
+        callerUserId: opts.callerUserId,
+    });
+    if (resolution.assigneeAgentIds) {
+        payload.assigneeAgentIds = resolution.assigneeAgentIds;
+    }
+    if (resolution.assigneeUserIds) {
+        payload.assigneeUserIds = resolution.assigneeUserIds;
+    }
+    return {
+        applied: resolution.applied,
+        source: resolution.source,
+        ...(resolution.assigneeAgentIds ? { agentIds: resolution.assigneeAgentIds } : {}),
+        ...(resolution.assigneeUserIds ? { userIds: resolution.assigneeUserIds } : {}),
+        ...(resolution.note ? { note: resolution.note } : {}),
+    };
+}
+/**
+ * An assignee field is itself an explicit choice, including an empty array.
+ * Empty arrays are the escape hatch for callers that intentionally want an
+ * unassigned task; defaulting must not turn an explicit clear into an agent
+ * assignment.
+ */
+function hasExplicitTaskAssignee(payload) {
+    return (Object.prototype.hasOwnProperty.call(payload ?? {}, 'assigneeAgentIds') ||
+        Object.prototype.hasOwnProperty.call(payload ?? {}, 'assigneeUserIds'));
+}
+/**
+ * Choose the implicit fallback policy for a task that has no assignee fields.
+ * Space/parent-scoped work can safely inherit the space lead (the same policy
+ * exposed by `--default-agent auto`). Personal work needs an unambiguous
+ * calling-agent identity and is resolved by the command layer.
+ */
+function implicitTaskDefaultAgentMode(payload, opts = {}) {
+    if (hasExplicitTaskAssignee(payload))
+        return undefined;
+    if (hasTaskAssignee(opts.existingTask))
+        return undefined;
+    // A task the caller declared human-executed must not be routed through the
+    // agent-defaulting path at all — not to a parent's agents, not to the space
+    // lead. `applyTaskAssigneeDefaults` answers it with a person instead.
+    if (!(0, data_provider_1.implicitAgentAssignmentAllowed)(payload.executionMode)) {
+        return undefined;
+    }
+    if (hasTaskAssignee(opts.parentPayload))
+        return 'auto';
+    const spaceId = stringValue(payload.spaceId ?? opts.existingTask?.spaceId);
+    return spaceId ? 'auto' : undefined;
+}
+async function applyDefaultAgentToPayload(payload, defaultAgent, opts = {}) {
+    const mode = typeof defaultAgent === 'string' ? defaultAgent.trim() : '';
+    if (!mode)
+        return { applied: false, source: 'none' };
+    // Every branch below ends in an AGENT assignee — a named agent, a parent's
+    // agents, or the space lead. None of them is a legal answer for a task the
+    // caller declared human-executed, and the implicit path never gets here
+    // (`implicitTaskDefaultAgentMode` returns undefined for it). So reaching this
+    // with `--execution-mode human` means the operator asked for both at once;
+    // say that, rather than building a payload the server will reject for a
+    // reason that does not name the flag that caused it.
+    if (!(0, data_provider_1.implicitAgentAssignmentAllowed)(payload.executionMode)) {
+        throw new Error('--default-agent assigns an Agent, which --execution-mode human forbids. ' +
+            'Drop one of them, or name the person with --assignee-user.');
+    }
+    if (hasExplicitTaskAssignee(payload)) {
+        return {
+            applied: false,
+            source: 'explicit-assignee',
+            agentIds: stringArray(payload.assigneeAgentIds),
+            userIds: stringArray(payload.assigneeUserIds),
+        };
+    }
+    if (hasTaskAssignee(opts.existingTask)) {
+        return {
+            applied: false,
+            source: 'existing-assignee',
+            agentIds: stringArray(opts.existingTask?.assigneeAgentIds),
+            userIds: stringArray(opts.existingTask?.assigneeUserIds),
+        };
+    }
+    const parentPayloadAgentIds = stringArray(opts.parentPayload?.assigneeAgentIds);
+    const parentPayloadUserIds = stringArray(opts.parentPayload?.assigneeUserIds);
+    if (parentPayloadAgentIds.length > 0 || parentPayloadUserIds.length > 0) {
+        inheritTaskAssignees(payload, opts.parentPayload);
+        return {
+            applied: true,
+            source: 'parent',
+            agentIds: parentPayloadAgentIds,
+            userIds: parentPayloadUserIds,
+        };
+    }
+    if (mode !== 'auto') {
+        payload.assigneeAgentIds = [mode];
+        return {
+            applied: true,
+            source: 'provided',
+            agentIds: [mode],
+        };
+    }
+    const parentId = stringValue(payload.parentId ?? opts.existingTask?.parentId);
+    if (parentId) {
+        const parentTask = await getCachedTask(parentId, opts.parentTaskCache);
+        const parentAgentIds = stringArray(parentTask.assigneeAgentIds);
+        const parentUserIds = stringArray(parentTask.assigneeUserIds);
+        if (parentAgentIds.length > 0 || parentUserIds.length > 0) {
+            inheritTaskAssignees(payload, parentTask);
+            return {
+                applied: true,
+                source: 'parent',
+                agentIds: parentAgentIds,
+                userIds: parentUserIds,
+            };
+        }
+        const parentSpaceId = stringValue(parentTask.spaceId);
+        if (!stringValue(payload.spaceId) && parentSpaceId) {
+            payload.spaceId = parentSpaceId;
+        }
+    }
+    const spaceId = stringValue(payload.spaceId ?? opts.existingTask?.spaceId);
+    if (!spaceId) {
+        throw new Error('--default-agent auto requires --space or a parent/existing task with a space');
+    }
+    if (!stringValue(payload.spaceId)) {
+        payload.spaceId = spaceId;
+    }
+    const space = await getCachedSpace(spaceId, opts.spaceCache);
+    const leadAgentId = stringValue(space.leadAgentId);
+    if (!leadAgentId) {
+        if (opts.allowUnassignedAuto) {
+            return { applied: false, source: 'none', spaceId };
+        }
+        throw new Error(`--default-agent auto could not resolve a lead agent for space ${spaceId}`);
+    }
+    payload.assigneeAgentIds = [leadAgentId];
+    return { applied: true, source: 'space-lead', agentIds: [leadAgentId], spaceId };
+}
+function createPatchFromCreatePayload(payload) {
+    const patch = {};
+    const copyFields = [
+        'title',
+        'description',
+        'descriptionFormat',
+        'priority',
+        'startDate',
+        'dueDate',
+        'goalId',
+        'spaceId',
+        'parentId',
+        'assigneeAgentIds',
+        'assigneeUserIds',
+        'executionMode',
+        'tags',
+        'labelIds',
+    ];
+    for (const field of copyFields) {
+        if (payload[field] !== undefined)
+            patch[field] = payload[field];
+    }
+    return patch;
+}
+function removeUndefinedFields(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined)
+            output[key] = value;
+    }
+    return output;
+}
+function listItems(response) {
+    if (Array.isArray(response))
+        return response;
+    const data = response?.data;
+    return Array.isArray(data) ? data : [];
+}
+function taskId(task) {
+    return String(task?.id ?? task?._id ?? '');
+}
+function taskRef(task) {
+    if (!task)
+        return '';
+    if (task.identifier)
+        return String(task.identifier);
+    if (task.taskNumber)
+        return `#${String(task.taskNumber)}`;
+    return '';
+}
+function formatTaskLabel(task) {
+    const id = taskId(task) || '?';
+    const ref = taskRef(task);
+    return `${id}${ref ? ` (${ref})` : ''} — ${String(task.title ?? '(no title)')}`;
+}
+function hasTaskAssignee(task) {
+    return (stringArray(task?.assigneeAgentIds).length > 0 || stringArray(task?.assigneeUserIds).length > 0);
+}
+function inheritTaskAssignees(payload, parent) {
+    const agentIds = stringArray(parent?.assigneeAgentIds);
+    const userIds = stringArray(parent?.assigneeUserIds);
+    if (agentIds.length > 0)
+        payload.assigneeAgentIds = agentIds;
+    if (userIds.length > 0)
+        payload.assigneeUserIds = userIds;
+    // Inheritance fills a gap; it never overrules a declaration. A caller who
+    // said `--execution-mode human` keeps it even when the parent is agent-run.
+    if (payload.executionMode === undefined &&
+        (parent?.executionMode === 'agent' || parent?.executionMode === 'human')) {
+        payload.executionMode = parent.executionMode;
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string' && item.trim().length > 0)
+        : [];
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+async function getCachedSpace(spaceId, cache) {
+    if (!cache) {
+        return (await data_provider_1.dataService.getSpace(spaceId));
+    }
+    if (!cache.has(spaceId)) {
+        cache.set(spaceId, data_provider_1.dataService.getSpace(spaceId));
+    }
+    return cache.get(spaceId);
+}
+async function getCachedTask(taskIdValue, cache) {
+    if (!cache) {
+        return (await data_provider_1.dataService.getTask(taskIdValue, { enrich: false }));
+    }
+    if (!cache.has(taskIdValue)) {
+        cache.set(taskIdValue, data_provider_1.dataService.getTask(taskIdValue, { enrich: false }));
+    }
+    return cache.get(taskIdValue);
+}
+async function getCachedProject(projectId, cache) {
+    const load = async () => {
+        const filtered = await projects_1.projectApi.search({ q: projectId, limit: 20 });
+        let exact = (0, projects_1.projectsFrom)(filtered).filter((project) => String(project.id ?? project._id ?? '') === projectId);
+        // The cross-space endpoint's `q` contract covers title/description/ref,
+        // not UUID. Fall back to the bounded visible project catalog so canonical
+        // IDs still resolve without inventing a second project read endpoint.
+        if (exact.length === 0) {
+            const catalog = await projects_1.projectApi.search({ limit: 200 });
+            exact = (0, projects_1.projectsFrom)(catalog).filter((project) => String(project.id ?? project._id ?? '') === projectId);
+        }
+        if (exact.length !== 1) {
+            throw new Error(exact.length > 1
+                ? `Project id ${projectId} matched multiple projects`
+                : `Project id ${projectId} was not found; pass a canonical project id or add --space`);
+        }
+        return exact[0];
+    };
+    if (!cache)
+        return load();
+    if (!cache.has(projectId))
+        cache.set(projectId, load());
+    return cache.get(projectId);
+}
+function normalizeTaskUpdateEntry(entry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        throw new Error('Each bulk update entry must be an object');
+    }
+    const record = entry;
+    const id = record.id ?? record.taskId;
+    if (!isNonEmptyString(id)) {
+        throw new Error('Each bulk update entry requires id or taskId');
+    }
+    const nestedPatch = record.data ?? record.patch ?? record.updates;
+    if (nestedPatch !== undefined) {
+        if (!nestedPatch || typeof nestedPatch !== 'object' || Array.isArray(nestedPatch)) {
+            throw new Error(`Bulk update ${id} has a non-object data/patch/updates field`);
+        }
+        return { id: String(id), patch: removeUndefinedFields(nestedPatch) };
+    }
+    const { id: _id, taskId: _taskId, ...rest } = record;
+    return { id: String(id), patch: removeUndefinedFields(rest) };
+}
+function normalizeBulkUpdateInput(input) {
+    let entries;
+    if (Array.isArray(input)) {
+        entries = input;
+    }
+    else if (input && typeof input === 'object') {
+        const record = input;
+        if (Array.isArray(record.updates)) {
+            entries = record.updates;
+        }
+        else if (Array.isArray(record.tasks)) {
+            entries = record.tasks;
+        }
+        else {
+            entries = Object.entries(record).map(([id, patch]) => ({ id, patch }));
+        }
+    }
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new Error('Bulk update JSON must be an array, or an object with updates/tasks array');
+    }
+    return entries.map(normalizeTaskUpdateEntry);
+}
+function normalizeStringField(payload, field, max) {
+    const value = payload[field];
+    if (typeof value !== 'string')
+        return;
+    const trimmed = value.trim();
+    if (trimmed) {
+        payload[field] = trimmed.slice(0, max);
+    }
+    else {
+        delete payload[field];
+    }
+}
+function envFirst(...names) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isBoundedString(value, min, max) {
+    return typeof value === 'string' && value.trim().length >= min && value.length <= max;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function formatApiError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}