@ctrl-spc/cs 0.7.10 → 0.7.12

package/dist/product-tools.js

@@ -76,6 +76,83 @@ export async function placeWorkItemHandler(client, args) {
     }
 }
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function listArtifactFoldersHandler(client, workItemId) {
+    try {
+        if (!UUID_RE.test(workItemId))
+            return errorResult('Use a valid work item ID.');
+        const task = await must(client.from('tasks').select('id').eq('id', workItemId).maybeSingle());
+        if (!task)
+            return errorResult('Work item not found or inaccessible.');
+        const artifacts = await must(client.from('artifacts')
+            .select('folder_name').eq('task_id', workItemId).is('deleted_at', null));
+        const counts = new Map();
+        for (const row of artifacts ?? [])
+            if (row.folder_name)
+                counts.set(row.folder_name, (counts.get(row.folder_name) ?? 0) + 1);
+        return textResult({ work_item_id: workItemId, folders: [...counts].sort(([a], [b]) => a.localeCompare(b))
+                .map(([name, artifact_count]) => ({ name, artifact_count })), unfiled_count: (artifacts ?? []).filter(row => !row.folder_name).length });
+    }
+    catch (error) {
+        return errorResult(`Could not list artifact folders: ${errorMessage(error)}`);
+    }
+}
+export async function setArtifactFolderHandler(client, artifactId, folderName) {
+    try {
+        if (!UUID_RE.test(artifactId))
+            return errorResult('Use a valid artifact ID.');
+        if (folderName !== null && (typeof folderName !== 'string' || folderName.length > 80))
+            return errorResult('Folder names must be 80 characters or fewer; use null for Unfiled.');
+        const artifact = await must(client.from('artifacts').update({ folder_name: folderName })
+            .eq('id', artifactId).is('deleted_at', null).select('id,task_id,title,folder_name,revision').maybeSingle());
+        if (!artifact)
+            return errorResult('Artifact not found or you do not have permission to move it.');
+        return textResult(artifact);
+    }
+    catch (error) {
+        return errorResult(`Could not set artifact folder: ${errorMessage(error)}`);
+    }
+}
+export async function workItemDependencyHandler(client, action, args) {
+    try {
+        const id = args.work_item_id, blockerId = args.depends_on_work_item_id;
+        if (!UUID_RE.test(id) || (action !== 'list' && (!blockerId || !UUID_RE.test(blockerId)))) {
+            return errorResult('Use valid work item IDs from list_tasks. No dependency was changed.');
+        }
+        const task = await must(client.from('tasks').select('id,project_id,archived_at,is_idea').eq('id', id).maybeSingle());
+        if (!task)
+            return errorResult('Work item not found or inaccessible. No dependency was changed.');
+        if (action === 'add') {
+            const blocker = await must(client.from('tasks').select('id,project_id,archived_at,is_idea').eq('id', blockerId).maybeSingle());
+            if (!blocker || blocker.project_id !== task.project_id)
+                return errorResult('Dependencies must connect accessible work items in the same project.');
+            if (task.archived_at || blocker.archived_at || task.is_idea || blocker.is_idea)
+                return errorResult('Choose active work items, not archived items or Product Ideas.');
+            if (id === blockerId)
+                return errorResult('A work item cannot depend on itself.');
+            const { error } = await client.from('task_dependencies').insert({ task_id: id, depends_on_task_id: blockerId });
+            if (error && error.code !== '23505')
+                throw new Error(error.message);
+        }
+        else if (action === 'remove') {
+            await must(client.from('task_dependencies').delete().match({ task_id: id, depends_on_task_id: blockerId }));
+        }
+        const [blockedBy, blocks] = await Promise.all([
+            must(client.from('task_dependencies')
+                .select('blocker:tasks!task_dependencies_depends_on_task_id_fkey(id,name,status)').eq('task_id', id)),
+            must(client.from('task_dependencies')
+                .select('dependent:tasks!task_dependencies_task_id_fkey(id,name,status)').eq('depends_on_task_id', id)),
+        ]);
+        if (action === 'remove' && blockedBy?.some(row => row.blocker.id === blockerId)) {
+            return errorResult('You do not have permission to remove this dependency.');
+        }
+        return textResult({ work_item_id: id, blocked_by: (blockedBy ?? []).map(row => row.blocker),
+            blocks: (blocks ?? []).map(row => row.dependent),
+            waiting: (blockedBy ?? []).some(row => row.blocker.status !== 'done') });
+    }
+    catch (error) {
+        return errorResult(`Could not ${action} work item dependency: ${errorMessage(error)}`);
+    }
+}
 export async function resolveFeedbackHandler(client, session, args) {
     try {
         if (!session) {
@@ -440,3 +517,459 @@ export function canonicalArgsHash(args) {
     };
     return createHash('sha256').update(JSON.stringify(canonical(args))).digest('hex');
 }
+/* ---------------------------------------------------------------------------
+ * Agile skeleton (feature 32, Slice 1) — `create_epic` / `create_sprint`,
+ * beside the grown `create_task` above.
+ *
+ * The agent lays out the WHOLE skeleton from one feature ask: an epic (what
+ * for), work items under it, sprints (ordered batches). Step −1 rulings
+ * (ux.md, 2026-07-30): DIRECT WRITE as the user under RLS — a skeleton of
+ * backlog items is un-started work, closer to an idea than an edit, so no
+ * propose queue; SMALL ORTHOGONAL TOOLS, not a composite draft pass;
+ * IDEMPOTENCE = read-before-write plus a duplicate-name refusal that teaches
+ * extending the existing structure instead of minting a parallel one.
+ *
+ * THE CALIBRATION RULE LIVES IN THE DESCRIPTIONS (teach-in-the-description
+ * doctrine): agents dramatically overestimate how long building takes because
+ * their training is saturated with human engineering timelines. The
+ * descriptions state the bias outright, size sprints as ordered batches of
+ * agent-executable work, and forbid duration estimates on items unless the
+ * user asked. Nothing here stores an estimate — there is no column for one,
+ * deliberately.
+ *
+ * GRANTS, verified against the seeded rows rather than assumed: members hold
+ * ('member','epic','create') (20260727080000 §4) and ('member','sprint',
+ * 'create') (20260708000000 init.sql §9), and no later migration revokes
+ * either — so the epics_insert / sprints_insert RLS policies already admit
+ * every org member and NO new grants migration is needed. A denial for some
+ * future role surfaces through the normal error path.
+ *
+ * NO cliv2_agent_outputs attribution row is written for an epic or a sprint:
+ * the kind check is ('artifact','comment','task','decision') and widening it
+ * is a migration this slice does not need — the skeleton's provenance is
+ * legible through its work items, which create_task already attributes.
+ * ------------------------------------------------------------------------- */
+/** Date args are refused by shape HERE (the resolveClient idiom) so a
+ *  malformed date gets a clean tool error instead of a Postgres cast failure
+ *  after other work happened. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** The project a skeleton tool writes into, resolved by id: UUID-shape-checked
+ *  before the read, and a miss (no such project, or one outside the caller's
+ *  orgs — RLS makes those indistinguishable on purpose) refused by id. */
+async function resolveSkeletonProject(client, projectIdArg, tool) {
+    const projectId = typeof projectIdArg === 'string' ? projectIdArg.trim() : '';
+    if (!projectId || !UUID_RE.test(projectId)) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: "${projectId}" is not a project id. Call list_tasks to see your projects and their ids. ` +
+                'Nothing was created.'),
+        };
+    }
+    const row = await must(client.from('projects').select('id, name').eq('id', projectId).maybeSingle());
+    if (!row) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: no project found for id "${projectId}". Nothing was created.`),
+        };
+    }
+    return { ok: true, value: row };
+}
+/** Refuse a malformed date arg by name; `undefined` passes (the arg is
+ *  optional everywhere it appears). */
+function validDateArg(tool, field, value) {
+    if (value === undefined)
+        return null;
+    if (!ISO_DATE_RE.test(value)) {
+        return errorResult(`${tool}: ${field} must be an ISO date (YYYY-MM-DD), got "${value}". Nothing was created.`);
+    }
+    return null;
+}
+/**
+ * Create an Epic in a project — writes public.epics as the user (RLS
+ * epics_insert, the 'epic'/'create' grant every member holds).
+ *
+ * THE DUPLICATE-NAME REFUSAL IS THE IDEMPOTENCE MECHANISM (Step −1 ruling 4):
+ * a re-run, or a "feature ABC v2" ask, must EXTEND the existing epic, not
+ * mint a second one — 24c's updating-beats-creating rule applied to
+ * structure. The match is case-insensitive on the trimmed name, against LIVE
+ * epics only: an archived epic has left the picker and can take no new work,
+ * so a fresh epic re-using its name is a legitimate new start, not a
+ * duplicate. The refusal lists the project's live epics so it doubles as the
+ * read surface the skeleton pass otherwise lacks (no epic-listing tool ships
+ * in this slice).
+ */
+export async function createEpicHandler(client, args) {
+    try {
+        const project = await resolveSkeletonProject(client, args.project_id, 'create_epic');
+        if (!project.ok)
+            return project.error;
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!name)
+            return errorResult('create_epic requires a non-empty name. Nothing was created.');
+        for (const [field, value] of [
+            ['start_date', args.start_date],
+            ['target_date', args.target_date],
+        ]) {
+            const refused = validDateArg('create_epic', field, value);
+            if (refused)
+                return refused;
+        }
+        // Mirrors the DB's epics_target_not_before_start check, refused where the
+        // agent can fix it instead of as a constraint violation.
+        if (args.start_date && args.target_date && args.target_date < args.start_date) {
+            return errorResult(`create_epic: target_date (${args.target_date}) is before start_date (${args.start_date}). ` +
+                'Nothing was created.');
+        }
+        const epics = (await must(client.from('epics').select('id, name, archived_at').eq('project_id', project.value.id))) ?? [];
+        const live = epics.filter((epic) => epic.archived_at === null);
+        const duplicate = live.find((epic) => epic.name.trim().toLowerCase() === name.toLowerCase());
+        if (duplicate) {
+            const listing = live.map((epic) => `"${epic.name}" (${epic.id})`).join(', ');
+            return errorResult(`create_epic: an epic named "${duplicate.name}" already exists in "${project.value.name}" ` +
+                `(id ${duplicate.id}). Do not create a duplicate — EXTEND the existing epic: create the new ` +
+                `work items with epic_id ${duplicate.id}, and reshape what already hangs under it. A re-run ` +
+                'or a "v2" ask extends the existing skeleton; it never mints a second one. Live epics in ' +
+                `this project: ${listing}. Nothing was created.`);
+        }
+        const epic = await must(client
+            .from('epics')
+            .insert({
+            project_id: project.value.id,
+            name,
+            ...(args.description?.trim() ? { description: args.description.trim() } : {}),
+            ...(args.start_date ? { start_date: args.start_date } : {}),
+            ...(args.target_date ? { target_date: args.target_date } : {}),
+        })
+            .select('id, project_id, name, description, start_date, target_date, created_at')
+            .single());
+        if (!epic)
+            throw new Error('Epic insert returned no row.');
+        return textResult({
+            epic,
+            note: 'Created as an empty epic — no work has started and none is declared. Place work items under ' +
+                "it with create_task's epic_id, sequence them with create_sprint + sprint_id, and add NO " +
+                'duration estimates to anything unless the user asked: sequencing is the value.',
+        });
+    }
+    catch (err) {
+        return errorResult(`create_epic failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Create a Sprint in a project — writes public.sprints as the user (RLS
+ * sprints_insert, the 'sprint'/'create' grant every member holds). Dates are
+ * optional (28 made the columns nullable): for agent-executed work a sprint is
+ * an ORDERED BATCH, not a time-box, and an invented fortnight is exactly the
+ * human-timeline bias this feature exists to counter.
+ *
+ * Same duplicate-name posture as create_epic, for the same reason: a re-run
+ * must extend the existing sprint sequence, never mint a parallel one.
+ */
+export async function createSprintHandler(client, args) {
+    try {
+        const project = await resolveSkeletonProject(client, args.project_id, 'create_sprint');
+        if (!project.ok)
+            return project.error;
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!name)
+            return errorResult('create_sprint requires a non-empty name. Nothing was created.');
+        for (const [field, value] of [
+            ['start_date', args.start_date],
+            ['end_date', args.end_date],
+        ]) {
+            const refused = validDateArg('create_sprint', field, value);
+            if (refused)
+                return refused;
+        }
+        // Mirrors the sprints table's own start <= end check (init.sql), refused
+        // where the agent can fix it.
+        if (args.start_date && args.end_date && args.end_date < args.start_date) {
+            return errorResult(`create_sprint: end_date (${args.end_date}) is before start_date (${args.start_date}). ` +
+                'Nothing was created.');
+        }
+        const sprints = (await must(client.from('sprints').select('id, name, archived_at').eq('project_id', project.value.id))) ?? [];
+        const live = sprints.filter((sprint) => sprint.archived_at === null);
+        const duplicate = live.find((sprint) => sprint.name.trim().toLowerCase() === name.toLowerCase());
+        if (duplicate) {
+            const listing = live.map((sprint) => `"${sprint.name}" (${sprint.id})`).join(', ');
+            return errorResult(`create_sprint: a sprint named "${duplicate.name}" already exists in "${project.value.name}" ` +
+                `(id ${duplicate.id}). Reuse it — place items into it with create_task's sprint_id — or name ` +
+                'the NEXT batch in the sequence; a re-run extends the existing sprint sequence, it never ' +
+                `mints a parallel one. Live sprints in this project: ${listing}. Nothing was created.`);
+        }
+        const sprint = await must(client
+            .from('sprints')
+            .insert({
+            project_id: project.value.id,
+            name,
+            ...(args.description !== undefined ? { description: args.description.trim() } : {}),
+            ...(args.start_date ? { start_date: args.start_date } : {}),
+            ...(args.end_date ? { end_date: args.end_date } : {}),
+        })
+            .select('id, project_id, name, description, start_date, end_date, created_at')
+            .single());
+        if (!sprint)
+            throw new Error('Sprint insert returned no row.');
+        return textResult({
+            sprint,
+            note: 'Created. Sprints for agent-executed work are ordered batches: the first holds what unblocks ' +
+                "everything else, each sized to what agents deliver in a session or a day. Place items with " +
+                "create_task's sprint_id, and add NO duration estimates unless the user asked.",
+        });
+    }
+    catch (err) {
+        return errorResult(`create_sprint failed: ${errorMessage(err)}`);
+    }
+}
+const STRUCTURE_TABLE = { epic: 'epics', sprint: 'sprints' };
+/**
+ * WHAT STRUCTURE THIS PROJECT HAS — the read that made "read before you write"
+ * possible (I13).
+ *
+ * LIVE ONES BY DEFAULT, because that is what "what exists" means to an agent
+ * about to add to it: an archived epic is not something to extend, and listing
+ * it invites a duplicate-name refusal the agent cannot act on. `include_archived`
+ * is deliberately NOT offered — nothing in this phase's Gherkin needs it, and
+ * YAGNI beats a flag with no caller.
+ *
+ * BOTH KINDS IN ONE CALL. They are always wanted together, and two tools would
+ * mean two round trips for the one question an agent actually has.
+ */
+export async function listStructureHandler(client, args) {
+    try {
+        const project = await resolveSkeletonProject(client, args.project_id, 'list_structure');
+        if (!project.ok)
+            return project.error;
+        const [epics, sprints] = await Promise.all([
+            must(client
+                .from('epics')
+                .select('id, name, description, start_date, target_date, created_at')
+                .eq('project_id', project.value.id)
+                .is('archived_at', null)
+                .order('created_at', { ascending: true })),
+            must(client
+                .from('sprints')
+                .select('id, name, description, start_date, end_date, created_at')
+                .eq('project_id', project.value.id)
+                .is('archived_at', null)
+                .order('created_at', { ascending: true })),
+        ]);
+        return textResult({
+            project: project.value,
+            epics: epics ?? [],
+            sprints: sprints ?? [],
+            note: 'Live epics and sprints only. Extend these rather than creating a near-duplicate — a ' +
+                'case-insensitive name match is refused. Place a work item with place_work_item, and see ' +
+                "where items already sit in list_tasks's epic and sprint fields.",
+        });
+    }
+    catch (err) {
+        return errorResult(`list_structure failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * RENAME OR ARCHIVE an epic or a sprint (I13).
+ *
+ * THE ARCHIVE RULE IS THE DATABASE'S, NOT THIS FUNCTION'S. A trigger refuses
+ * archiving anything that still has unfinished work
+ * (`app.guard_epic_archive` / `app.guard_sprint_archive`, SQLSTATE PT423). This
+ * does not pre-check it — a client-side check would read a snapshot of a table
+ * this write does not touch, so it can be stale, and duplicating the rule means
+ * two places to keep in step. It translates the refusal instead.
+ *
+ * THE MACHINE TOKEN NEVER REACHES THE AGENT. The raise's message is
+ * `epic_archive_blocked`, which the shipped web UI is explicit must never be
+ * rendered; the SAME rule applies to a tool result, which is read by an agent
+ * that will repeat it to the user. Keyed off SQLSTATE, exactly as
+ * `archiveErrorMessage` in ProjectSettings.tsx does, and the sentence says what
+ * would unblock it — the Gherkin asserts all three.
+ */
+export async function updateStructureHandler(client, args) {
+    try {
+        const kind = typeof args.kind === 'string' ? args.kind.trim().toLowerCase() : '';
+        if (kind !== 'epic' && kind !== 'sprint') {
+            return errorResult(`update_structure: kind must be "epic" or "sprint", got "${args.kind ?? ''}". Nothing was changed.`);
+        }
+        const table = STRUCTURE_TABLE[kind];
+        const id = typeof args.id === 'string' ? args.id.trim() : '';
+        if (!id || !UUID_RE.test(id)) {
+            return errorResult(`update_structure: "${id}" is not a ${kind} id. Call list_structure to see them. Nothing was changed.`);
+        }
+        const name = typeof args.name === 'string' ? args.name.trim() : undefined;
+        if (args.name !== undefined && !name) {
+            return errorResult(`update_structure: name cannot be blank. Nothing was changed.`);
+        }
+        if (name === undefined && args.archived === undefined && args.description === undefined
+            && args.start_date === undefined && args.end_date === undefined && args.target_date === undefined) {
+            return errorResult('update_structure: pass a name, description, date, or archived setting — there is nothing to change. ' +
+                'Nothing was changed.');
+        }
+        const current = await must(client.from(table).select('*').eq('id', id).maybeSingle());
+        if (!current) {
+            return errorResult(`update_structure: no ${kind} found for id "${id}". Nothing was changed.`);
+        }
+        /* THE SAME DUPLICATE-NAME RULE THE CREATE TOOLS ENFORCE. Without it, rename
+           is a way around the refusal `create_epic` gives — two live epics with one
+           name, reached by creating under a throwaway name and renaming. Scoped to
+           LIVE rows in the same project, and it ignores the row being renamed so
+           that setting a name to itself is not a conflict. */
+        if (name !== undefined && name.toLowerCase() !== current.name.trim().toLowerCase()) {
+            const siblings = (await must(client
+                .from(table)
+                .select('id, name')
+                .eq('project_id', current.project_id)
+                .is('archived_at', null))) ?? [];
+            const clash = siblings.find((row) => row.id !== id && row.name.trim().toLowerCase() === name.toLowerCase());
+            if (clash) {
+                return errorResult(`update_structure: a live ${kind} named "${clash.name}" already exists in this project ` +
+                    `(id ${clash.id}). Use that one, or pick a different name. Nothing was changed.`);
+            }
+        }
+        if (kind === 'epic' && args.end_date !== undefined)
+            return errorResult('Use target_date for an epic.');
+        if (kind === 'sprint' && args.target_date !== undefined)
+            return errorResult('Use end_date for a sprint.');
+        const patch = {};
+        if (args.description !== undefined)
+            patch.description = args.description.trim();
+        for (const field of ['start_date', 'end_date', 'target_date']) {
+            if (args[field] === undefined)
+                continue;
+            const refusal = validDateArg('update_structure', field, args[field] ?? undefined);
+            if (refusal)
+                return refusal;
+            patch[field] = args[field];
+        }
+        if (name !== undefined)
+            patch.name = name;
+        /* THE DATABASE OWNS THE TIMESTAMP. The guard trigger coalesces whatever is
+           sent on the archiving transition to `now()`, so this sends a marker
+           instant rather than pretending to choose one; restoring sends null, which
+           the trigger leaves alone. */
+        if (args.archived !== undefined)
+            patch.archived_at = args.archived ? new Date().toISOString() : null;
+        const { data, error } = await client
+            .from(table)
+            .update(patch)
+            .eq('id', id)
+            .select('*')
+            .maybeSingle();
+        if (error) {
+            /* PT423 — the archive guard. The sentence is OURS: the raise's message is
+               a machine token (`epic_archive_blocked`) and must never be repeated to
+               the user. The database's own `hint` says the same thing, but keying off
+               the stable SQLSTATE rather than parsing prose is what the web does. */
+            if (error.code === 'PT423') {
+                return errorResult(`update_structure: this ${kind} still has work items that are not done, so it cannot be ` +
+                    `archived. Finish them or move them to another ${kind} first, then archive it. ` +
+                    'Nothing was changed.');
+            }
+            if (error.code === '23514')
+                return errorResult('The end or target date must not be before the start date. Nothing was changed.');
+            throw new Error(error.message);
+        }
+        /* RLS REFUSING A WRITE RETURNS NO ERROR AND NO ROW — the silent-failure
+           shape this repo has been bitten by before. Reported as a refusal rather
+           than as success. */
+        if (!data) {
+            return errorResult(`update_structure: the ${kind} could not be changed — it may have been removed, or you may ` +
+                'not have permission. Nothing was changed.');
+        }
+        return textResult({
+            [kind]: data,
+            note: args.archived
+                ? `Archived. Its work items survive and keep their other placements.`
+                : 'Updated.',
+        });
+    }
+    catch (err) {
+        return errorResult(`update_structure failed: ${errorMessage(err)}`);
+    }
+}
+async function artifactStructure(client, kind, id) {
+    if ((kind !== 'epic' && kind !== 'sprint') || !UUID_RE.test(id))
+        throw new Error('Choose an epic or sprint and its valid ID.');
+    const parent = await must(client.from(kind === 'epic' ? 'epics' : 'sprints').select('id,name,project_id,archived_at').eq('id', id).maybeSingle());
+    if (!parent)
+        throw new Error('The epic or sprint is missing or inaccessible.');
+    return parent;
+}
+export async function listStructureArtifactsHandler(client, kind, structureId) {
+    try {
+        const parent = await artifactStructure(client, kind, structureId);
+        const artifacts = await must(client.from('structure_artifacts').select('id,title,type,format,revision,created_at,updated_at')
+            .eq(kind === 'epic' ? 'epic_id' : 'sprint_id', structureId).is('deleted_at', null).order('created_at'));
+        return textResult({ structure: parent, artifacts });
+    }
+    catch (error) {
+        return errorResult(`Could not list artifacts: ${errorMessage(error)}`);
+    }
+}
+export async function getStructureArtifactHandler(client, artifactId) {
+    try {
+        if (!UUID_RE.test(artifactId))
+            throw new Error('Use a valid artifact ID.');
+        const artifact = await must(client.from('structure_artifacts').select('*').eq('id', artifactId).is('deleted_at', null).maybeSingle());
+        if (!artifact)
+            throw new Error('Artifact is missing or inaccessible.');
+        return textResult(artifact);
+    }
+    catch (error) {
+        return errorResult(`Could not read artifact: ${errorMessage(error)}`);
+    }
+}
+export async function createStructureArtifactHandler(client, userId, args) {
+    try {
+        const parent = await artifactStructure(client, args.kind, args.structure_id);
+        if (parent.archived_at)
+            throw new Error('Restore the epic or sprint before adding artifacts.');
+        if (!args.title.trim() || !args.content.trim())
+            throw new Error('Give the artifact a title and content.');
+        const artifact = await must(client.from('structure_artifacts').insert({ project_id: parent.project_id,
+            [args.kind === 'epic' ? 'epic_id' : 'sprint_id']: parent.id, title: args.title.trim(), type: args.type,
+            format: args.format ?? 'md', content: args.content, created_by: userId }).select('*').single());
+        if (!artifact)
+            throw new Error('Artifact was not created.');
+        return textResult({ artifact, structure: parent, kind: args.kind });
+    }
+    catch (error) {
+        return errorResult(`Could not create artifact: ${errorMessage(error)}`);
+    }
+}
+export async function updateStructureArtifactHandler(client, args) {
+    try {
+        if (!UUID_RE.test(args.artifact_id) || !Number.isInteger(args.expected_revision) || args.expected_revision < 1)
+            throw new Error('Read the artifact first and pass its current revision.');
+        const patch = {};
+        for (const key of ['title', 'content', 'type', 'format'])
+            if (args[key] !== undefined)
+                patch[key] = args[key];
+        if (args.archived !== undefined)
+            patch.deleted_at = args.archived ? new Date().toISOString() : null;
+        if (!Object.keys(patch).length)
+            throw new Error('Pass at least one field to change.');
+        const artifact = await must(client.from('structure_artifacts').update(patch).eq('id', args.artifact_id)
+            .eq('revision', args.expected_revision).select('*').maybeSingle());
+        if (!artifact)
+            throw new Error('Artifact changed, is missing, or you cannot edit it. Read it again before retrying; nothing was overwritten.');
+        return textResult(artifact);
+    }
+    catch (error) {
+        return errorResult(`Could not update artifact: ${errorMessage(error)}`);
+    }
+}
+export async function searchAgentCardsHandler(client, args) {
+    try {
+        const limit = Math.max(1, Math.min(args.limit ?? 100, 1000)), offset = Math.max(args.offset ?? 0, 0);
+        const cards = await must(client.rpc('panel3_search_cards', {
+            p_query: args.query ?? '', p_work_item_id: args.work_item_id ?? null,
+            p_archived: args.archived ?? null, p_limit: limit, p_offset: offset,
+        }));
+        if (!cards)
+            throw new Error('Search returned no result. Try again.');
+        return textResult({ cards, next_offset: cards.length === limit ? offset + limit : null });
+    }
+    catch (error) {
+        return errorResult(`Could not search agent cards: ${errorMessage(error)}`);
+    }
+}

package/dist/workflow-tool-mentions.js

@@ -21,6 +21,17 @@ export const WORKFLOW_TOOLS = [
     { id: 'create_product_idea', name: 'Create Product Idea', detail: 'Capture future work without starting implementation.', alwaysAllowed: false, advanced: false },
     { id: 'create_epic', name: 'Create Epic', detail: 'Group related work items in a project.', alwaysAllowed: false, advanced: true },
     { id: 'create_sprint', name: 'Create Sprint', detail: 'Create an ordered batch of work.', alwaysAllowed: false, advanced: true },
+    { id: 'list_structure', name: 'Read Epics and Sprints', detail: 'Read descriptions and dates for project planning.', alwaysAllowed: true, advanced: true },
+    { id: 'update_structure', name: 'Edit Epic or Sprint', detail: 'Update descriptions, dates, names, or archive state.', alwaysAllowed: false, advanced: true },
+    { id: 'list_structure_artifacts', name: 'Read Epic or Sprint Artifacts', detail: 'Find artifacts attached to an epic or sprint.', alwaysAllowed: true, advanced: true },
+    { id: 'get_structure_artifact', name: 'Read Epic or Sprint Artifact', detail: 'Read its content and revision.', alwaysAllowed: true, advanced: true },
+    { id: 'create_structure_artifact', name: 'Create Epic or Sprint Artifact', detail: 'Write an artifact directly on an epic or sprint.', alwaysAllowed: false, advanced: true },
+    { id: 'update_structure_artifact', name: 'Edit Epic or Sprint Artifact', detail: 'Revise or remove an artifact using its current revision.', alwaysAllowed: false, advanced: true },
+    { id: 'list_artifact_folders', name: 'Read Artifact Folders', detail: 'Find existing folders on a work item.', alwaysAllowed: true, advanced: true },
+    { id: 'set_artifact_folder', name: 'Set Artifact Folder', detail: 'File an artifact in one folder or move it to Unfiled.', alwaysAllowed: false, advanced: true },
+    { id: 'list_work_item_dependencies', name: 'Read Dependencies', detail: 'See what blocks a work item and what it blocks.', alwaysAllowed: true, advanced: true },
+    { id: 'add_work_item_dependency', name: 'Add Dependency', detail: 'Make a work item wait for another to finish.', alwaysAllowed: false, advanced: true },
+    { id: 'remove_work_item_dependency', name: 'Remove Dependency', detail: 'Remove a work item dependency.', alwaysAllowed: false, advanced: true },
     { id: 'place_work_item', name: 'Move Work Item', detail: 'Place work in an epic or sprint, or remove that placement.', alwaysAllowed: false, advanced: true },
     { id: 'reorder_backlog', name: 'Reorder Backlog', detail: 'Change the order in which backlog work is picked up.', alwaysAllowed: false, advanced: true },
     { id: 'propose_project_context', name: 'Propose Project Context', detail: 'Submit project guidance for review in Project settings.', alwaysAllowed: false, advanced: true },
@@ -112,6 +123,7 @@ export function authorToolMentions(body) {
 }
 export const WORKFLOW_AUTHORING_TEACHING = 'When the user asks you to create a workflow, build it in the library; do not merely describe it or execute it. ' +
     'Use ask_question for missing requirements that materially change the workflow, then continue after the answer. ' +
+    'If the user requests plain prose or no tool mentions, write plain Markdown only: do not add tool links, permissions, or an approval template. ' +
     'Encode every requested tool use and permission as a Markdown mention in the stage body. ' +
     'Use compact links: [@Create Artifact](ctrl-spc://tool/create_artifact?approval=not-required) to write a plan without asking; ' +
     '[@Ask Question](ctrl-spc://tool/ask_question?approval=not-required) to review its output; ' +

package/dist/workflows.js

@@ -144,6 +144,7 @@ export async function buildWorkflow(client, input) {
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
+    input.branches?.forEach((branch, i) => prose.push([`branch ${i + 1} condition`, branch.when]));
     for (const [field, value] of prose) {
         const token = absolutePathToken(value);
         if (token) {
@@ -158,8 +159,9 @@ export async function buildWorkflow(client, input) {
         p_description: input.description,
         p_stages: input.stages,
         p_exits: input.exits,
-        p_branches: [],
+        p_branches: (input.branches ?? []).map(branch => ({ when: branch.when, runs_workflow_id: branch.runsWorkflowId })),
         p_from_agent: input.fromAgent,
+        ...(input.ending === undefined ? {} : { p_ending: input.ending }),
     });
     if (error)
         throw new Error(`could not create workflow ${input.name}: ${error.message}`);
@@ -239,11 +241,8 @@ export async function rewordStage(client, input) {
  * behalf. Its refusals come back verbatim behind one sentence naming what was
  * being edited.
  *
- * ═══ BRANCHES ARE PASSED BACK AS THEY WERE READ. ═══ The RPC replaces them from
- * `p_branches`, and nothing in v3 sets one, so the caller hands back the list
- * `readWorkflow` read a moment before. A branch written between that read and
- * this call is lost, which is the posture the web's `replaceStructure` records
- * for itself.
+ * Branches are the complete replacement list. Callers preserve the current
+ * list when no branch change was requested, matching the web editor.
  *
  * ═══ NULL NAME OR DESCRIPTION MEANS UNCHANGED, ═══ which is the RPC's own
  * contract: an agent adding a stage does not restate a name it is not touching.
@@ -257,6 +256,7 @@ export async function editWorkflow(client, input) {
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
+    input.branches.forEach((branch, i) => prose.push([`branch ${i + 1} condition`, branch.when]));
     for (const [field, value] of prose) {
         const token = value === null ? null : absolutePathToken(value);
         if (token) {
@@ -273,6 +273,7 @@ export async function editWorkflow(client, input) {
         p_exits: input.exits,
         p_branches: input.branches.map((branch) => ({ when: branch.when, runs_workflow_id: branch.runsWorkflowId })),
         p_from_agent: input.fromAgent,
+        ...(input.ending === undefined ? {} : { p_ending: input.ending }),
     });
     if (error)
         throw new Error(`could not edit the workflow: ${error.message}`);
@@ -323,7 +324,7 @@ export async function validateWorkflowToolTarget(client, workItemId, tool, args)
         if (targetId && targetId !== workItemId)
             throw new Error('The tool mention belongs to the current workflow work item. Nothing was written.');
     }
-    if (tool === 'update_artifact') {
+    if (tool === 'update_artifact' || tool === 'set_artifact_folder') {
         const artifacts = await read(client.from('artifacts').select('task_id')
             .eq('id', args.artifact_id ?? args.id), 'the artifact work item');
         if (artifacts.length !== 1 || artifacts[0].task_id !== workItemId)
@@ -343,6 +344,19 @@ export async function validateWorkflowToolTarget(client, workItemId, tool, args)
             throw new Error('Feedback is missing or outside the workflow work item. Nothing was written.');
         }
     }
+    if (tool === 'update_structure' || tool === 'create_structure_artifact' || tool === 'list_structure_artifacts'
+        || tool === 'get_structure_artifact' || tool === 'update_structure_artifact') {
+        const artifactAction = tool === 'get_structure_artifact' || tool === 'update_structure_artifact';
+        const table = artifactAction ? 'structure_artifacts' : args.kind === 'epic' ? 'epics' : args.kind === 'sprint' ? 'sprints' : null;
+        if (!table)
+            throw new Error('Choose an epic or sprint. Nothing was written.');
+        const [source, destination] = await Promise.all([
+            read(client.from('tasks').select('project_id').eq('id', workItemId), 'the workflow project'),
+            read(client.from(table).select('project_id').eq('id', artifactAction ? args.artifact_id : args.structure_id ?? args.id), 'the destination project'),
+        ]);
+        if (source.length !== 1 || destination.length !== 1 || source[0].project_id !== destination[0].project_id)
+            throw new Error('This action is outside the workflow project. Nothing was written.');
+    }
     if (args.project_id || (targetId && targetId !== workItemId)) {
         const items = await read(client.from('tasks').select('id, project_id')
             .in('id', [...new Set([workItemId, ...(targetId ? [String(targetId)] : [])])]), 'the workflow project');