npm - @ctrl-spc/cs - Versions diffs - 0.7.2 → 0.7.3 - Mend

@ctrl-spc/cs 0.7.2 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/login.js CHANGED Viewed

@@ -137,7 +137,15 @@ function renderPage(state) {
   input { padding:8px 10px; font-size:14px; border:1px solid #ccc; border-radius:6px; }
   button[type=submit] { margin-top:6px; padding:9px; border:none; border-radius:6px; background:#111; color:#fff; cursor:pointer; }
   .error { color:#c0392b; font-size:13px; min-height:16px; }
-  @media (prefers-color-scheme: dark){ body{background:#111;color:#eee;} input{background:#1c1c1c;border-color:#333;color:#eee;} button[type=submit]{background:#eee;color:#111;} }
+  @media (prefers-color-scheme: dark){
+    body{background:#111;color:#eee;} p.sub{color:#999;}
+    input{background:#1c1c1c;border-color:#333;color:#eee;}
+    button[type=submit]{background:#eee;color:#111;}
+    .tabs{border-bottom-color:#333;}
+    .tabs button{color:#999;}
+    .tabs button.active{color:#fff;border-bottom-color:#fff;}
+    .error{color:#ff6b5e;}
+  }
 </style></head><body>
 <div id="app">
   <h1>CTRL+SPC</h1><p class="sub">Sign in to link this computer.</p>

package/dist/mcp.js CHANGED Viewed

@@ -4756,7 +4756,13 @@ export async function listCredentialsHandler(client) {
  * returns `{secret, username}`; that maps to screen 8's shapes —
  * api_key → `{kind, secret}`, login → `{kind, username, password}`.
  */
-export async function getCredentialHandler(client, args,
+export async function getCredentialHandler(client,
+// `id` is the web's copy-for-agent handle, and it is the ONLY thing that can
+// resolve the ambiguity the name path can only report: names are unique per
+// (org, creator), so two credentials the caller can read may share one, and
+// by name this tool could previously do nothing but tell the user to go
+// rename something. A pasted id names the row the user actually clicked.
+args,
 // 18d Slice 3. OPTIONAL and trailing, so the existing two-argument call sites
 // (and their tests) are untouched. Absent means "not a run" — see
 // `rememberSecret`.
@@ -4765,26 +4771,38 @@ runTodoId = null) {
     // whatever casing the agent happened to type: the match below is
     // case-insensitive, so "talenttrack read token" must still redact as
     // "[redacted: TalentTrack read token]".
+    const wantedId = typeof args.id === 'string' ? args.id.trim() : '';
+    if (!wantedId && !args.name) {
+        return errorResult('get_credential requires name — as listed by list_credentials.');
+    }
     let match;
     try {
         const rows = (await must(client
             .from('credentials')
             .select('id, name, kind, org_id, created_by')
             .order('created_at', { ascending: true }))) ?? [];
-        const wanted = args.name.toLowerCase();
-        // Uniqueness is per (org, creator): the caller can see two credentials
-        // with the same lowercased name across two of their orgs, or within one
-        // org (their own plus one shared to them by another creator). Never guess
-        // which secret was meant. org_id/created_by are read only to word this
-        // error; they never appear in tool output.
-        const matches = rows.filter((row) => row.name.toLowerCase() === wanted);
-        if (matches.length > 1) {
-            const sameOrg = matches.every((row) => row.org_id === matches[0].org_id);
-            return errorResult(sameOrg
-                ? `credential name "${args.name}" is ambiguous — you can access more than one credential with this name in the same organization (e.g. your own and one shared with you); delete or re-create yours under a different name, or ask an org owner to revoke a shared copy`
-                : `credential name "${args.name}" is ambiguous — you have access to credentials with this name in more than one of your organizations; delete or re-create one under a different name`);
-        }
-        match = matches[0];
+        if (wantedId) {
+            // An id names one row, so there is no ambiguity branch to reach. RLS
+            // already filtered the rows, so a credential the caller cannot read is
+            // simply absent and falls through to the uniform not-found below.
+            match = rows.find((row) => row.id === wantedId);
+        }
+        else {
+            const wanted = args.name.toLowerCase();
+            // Uniqueness is per (org, creator): the caller can see two credentials
+            // with the same lowercased name across two of their orgs, or within one
+            // org (their own plus one shared to them by another creator). Never guess
+            // which secret was meant. org_id/created_by are read only to word this
+            // error; they never appear in tool output.
+            const matches = rows.filter((row) => row.name.toLowerCase() === wanted);
+            if (matches.length > 1) {
+                const sameOrg = matches.every((row) => row.org_id === matches[0].org_id);
+                return errorResult(sameOrg
+                    ? `credential name "${args.name}" is ambiguous — you can access more than one credential with this name in the same organization (e.g. your own and one shared with you); delete or re-create yours under a different name, or ask an org owner to revoke a shared copy`
+                    : `credential name "${args.name}" is ambiguous — you have access to credentials with this name in more than one of your organizations; delete or re-create one under a different name`);
+            }
+            match = matches[0];
+        }
     }
     catch (err) {
         return errorResult(`get_credential failed: ${err.message}`);
@@ -4978,9 +4996,51 @@ export async function listSkillsHandler(client, args) {
  * survives a compaction — an agent that has lost `get_skill`'s output still has
  * the skill's name in the conversation and can still reach its files.
  */
-async function resolveSkill(client, rawName, rawOrgId, tool) {
+/**
+ * Resolve a skill by its row id — the handle the web's copy-for-agent button
+ * pastes. An id names ONE row, so neither of the name path's two ambiguity
+ * errors can arise and `org_id` has nothing left to disambiguate: the id
+ * already decided which org's skill this is, and the bundle it belongs to says
+ * which org that was. RLS does the access check, so a row the caller cannot see
+ * is simply not found.
+ */
+async function resolveSkillById(client, id, tool) {
+    const rows = (await must(client
+        .from('skills')
+        .select('id, bundle_id, name, description, relative_path, status, status_reason')
+        .eq('id', id)
+        .is('deleted_at', null))) ?? [];
+    const row = rows[0];
+    if (!row) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: no skill with id ${id}. It may have been deleted, or belong to an organization you ` +
+                'cannot see. Call list_skills to see the skills that exist.'),
+        };
+    }
+    // The bundle is what carries the org, and only a LIVE bundle counts: a skill
+    // row can outlive the archiving of the bundle that brought it in.
+    const bundles = await liveSkillBundles(client, null);
+    const orgId = bundles.find((bundle) => bundle.id === row.bundle_id)?.org_id;
+    if (!orgId) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: skill "${row.name}" belongs to a skill pack that is no longer active. ` +
+                'Re-import the pack in the web app.'),
+        };
+    }
+    return { ok: true, value: { row, orgId } };
+}
+async function resolveSkill(client, rawName, rawOrgId, tool,
+// The web's copy-for-agent handle. A name is still the addressing an agent
+// reaches for unaided (it survives a compaction; see this section's header),
+// so `id` is the ALTERNATIVE, not the replacement: it exists because the
+// Skills page copies `/ctrl-spc skill <id>` and a pasted row must resolve to
+// the row the user clicked, never to a same-named skill in another org.
+rawId = undefined) {
+    const wantedId = typeof rawId === 'string' ? rawId.trim() : '';
     const wanted = typeof rawName === 'string' ? rawName.trim() : '';
-    if (!wanted) {
+    if (!wantedId && !wanted) {
         return {
             ok: false,
             error: errorResult(`${tool} requires name — the name of the skill to read, as listed by list_skills.`),
@@ -4989,6 +5049,8 @@ async function resolveSkill(client, rawName, rawOrgId, tool) {
     const filter = skillOrgFilter(rawOrgId, tool);
     if (!filter.ok)
         return filter;
+    if (wantedId)
+        return resolveSkillById(client, wantedId, tool);
     const bundles = await liveSkillBundles(client, filter.value);
     const orgIdByBundle = new Map(bundles.map((bundle) => [bundle.id, bundle.org_id]));
     const rows = orgIdByBundle.size
@@ -5167,7 +5229,7 @@ async function listSkillBundleFiles(client, orgId, bundleId, relativePath) {
 }
 export async function getSkillHandler(client, args) {
     try {
-        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'get_skill');
+        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'get_skill', args?.id);
         if (!resolved.ok)
             return resolved.error;
         const { row: match, orgId } = resolved.value;
@@ -5276,7 +5338,7 @@ export async function readSkillFileHandler(client, args) {
         if (!wantedPath) {
             return errorResult('read_skill_file requires path — one of the paths get_skill listed in bundle_files.');
         }
-        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'read_skill_file');
+        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'read_skill_file', args?.id);
         if (!resolved.ok)
             return resolved.error;
         const { row: match, orgId } = resolved.value;
@@ -5883,6 +5945,58 @@ async function unnarrowedEmptyNote(client, projectId) {
     }
     return NO_PROJECT_DOCUMENTS_NOTE;
 }
+export async function getDocumentHandler(client, args) {
+    const id = typeof args.id === 'string' ? args.id.trim() : '';
+    if (!id) {
+        return errorResult('get_document requires id — the id of the document to read, as the web app’s “Copy for agent” ' +
+            'button pastes it.');
+    }
+    // Shape-checked once, here at the boundary, exactly as resolveContextProject
+    // does with task_id: without it a mistyped id comes back as a Postgres
+    // "invalid input syntax for type uuid", which reads like a bug in the tool.
+    if (!UUID_RE.test(id)) {
+        return errorResult(`get_document: not a valid document id: "${id}".`);
+    }
+    try {
+        // Context documents first, then instructions. RLS scopes both reads, so a
+        // row the caller may not see is simply absent and falls through to the
+        // not-found below.
+        const documents = await must(client
+            .from('project_documents')
+            .select('title, content, codebase_id, type')
+            .eq('id', id));
+        const document = (documents ?? [])[0];
+        if (document)
+            return textResult(shapeDocument(document));
+        const instructions = await must(client.from('agent_instructions').select('title, content, codebase_id').eq('id', id));
+        const instruction = (instructions ?? [])[0];
+        if (instruction) {
+            return textResult({
+                ...shapeDocument(instruction),
+                // Said plainly, so an agent that fetched one does not conclude these are
+                // reference material it may choose to consult: it already has them.
+                note: 'This is an agent instruction. Every instruction on this project is already delivered in ' +
+                    'your prompt — reading one here does not make it optional.',
+            });
+        }
+        return errorResult(`get_document: no document with id ${id}. It may have been deleted, or belong to a project you ` +
+            'cannot see. Call get_project_context to read the documents on the project you are working.');
+    }
+    catch (err) {
+        return errorResult(`get_document failed: ${errorMessage(err)}`);
+    }
+}
+/** The one shape both tables report in, so a caller never has to branch on
+ *  which table answered. `scope` is what `codebase_id` MEANS — null is the
+ *  project's own document, a value is that codebase's. */
+function shapeDocument(row) {
+    return {
+        title: row.title,
+        ...(row.type ? { type: row.type } : {}),
+        scope: row.codebase_id === null ? 'project' : 'codebase',
+        content: row.content,
+    };
+}
 // ---------------------------------------------------------------------------
 // Project context (feature 13a, Phase 4) — `propose_project_context`.
 //
@@ -9802,6 +9916,7 @@ export const TOOL_NAMES = [
     'get_skill',
     'read_skill_file',
     'get_project_context',
+    'get_document',
     'propose_project_context',
     'list_product_ideas',
     'create_product_idea',
@@ -11216,7 +11331,16 @@ runTodoIdSource = null) {
             'comments, artifacts, documents and questions, and name the credential instead. Never refuse the ' +
             'work to avoid touching the value.',
         inputSchema: {
-            name: z.string().min(1).describe('Credential name, as listed by list_credentials'),
+            name: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Credential name, as listed by list_credentials'),
+            id: z
+                .string()
+                .optional()
+                .describe('Credential id, as pasted by the web app\'s "Copy for agent" button. Use it instead of ' +
+                'name; it names exactly one credential, where a name can be ambiguous.'),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -11250,7 +11374,12 @@ runTodoIdSource = null) {
             'about to do. If two organizations hold a skill of the same name this refuses rather than ' +
             'guessing: pass org_id to say which you mean. Read-only.',
         inputSchema: {
-            name: z.string().min(1).describe('Skill name, as listed by list_skills'),
+            name: z.string().min(1).optional().describe('Skill name, as listed by list_skills'),
+            id: z
+                .string()
+                .optional()
+                .describe('Skill id, as pasted by the web app\'s "Copy for agent" button. Use it instead of name; ' +
+                'it names exactly one skill, so org_id is never needed with it.'),
             org_id: z
                 .string()
                 .optional()
@@ -11266,7 +11395,11 @@ runTodoIdSource = null) {
             'those paths here. WHEN A SKILL POINTS AT A FILE BESIDE IT, FETCH IT AND FOLLOW IT — never ask ' +
             'the user to supply a file the organization already stored. Text only, up to 512 KB. Read-only.',
         inputSchema: {
-            name: z.string().min(1).describe('Skill name, as listed by list_skills'),
+            name: z.string().min(1).optional().describe('Skill name, as listed by list_skills'),
+            id: z
+                .string()
+                .optional()
+                .describe('Skill id. Use it instead of name; it names exactly one skill.'),
             path: z
                 .string()
                 .min(1)
@@ -11313,6 +11446,22 @@ runTodoIdSource = null) {
         touchSession(connectionId);
         return getProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('get_document', {
+        description: 'Read ONE context document or agent instruction by its id — the whole document, not an excerpt. ' +
+            'Use it when someone hands you an id (the web app’s “Copy for agent” button pastes one), or when ' +
+            'get_project_context named a document you need in full. It resolves either kind, so you do not ' +
+            'need to know which one the id belongs to. To read a project’s context as a whole instead, call ' +
+            'get_project_context. Read-only.',
+        inputSchema: {
+            id: z
+                .string()
+                .min(1)
+                .describe('Document id, as the web app’s “Copy for agent” button pastes it'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return getDocumentHandler(client, args);
+    });
     server.registerTool('propose_project_context', {
         // The description TEACHES: when to reach for this (after reading a repo),
         // what a good proposal is (content it actually read, one line of why),

package/dist/skills.js CHANGED Viewed

@@ -15,7 +15,7 @@ import { dirname, join } from 'node:path';
  */
 // Verbatim from the web/skill contract the copied `/ctrl-spc work <id>`
 // invocation depends on.
-const SKILL_DESCRIPTION = 'Work a CTRL+SPC work item or artifact by ID — delegates read-only exploration and writes analysis/plans/specs/diagrams/mocks/wireframes back via the ctrl-spc MCP tools. Use when the user pastes /ctrl-spc work <id> or /ctrl-spc artifact <id>.';
+const SKILL_DESCRIPTION = 'Work a CTRL+SPC work item or artifact by ID — delegates read-only exploration and writes analysis/plans/specs/diagrams/mocks/wireframes back via the ctrl-spc MCP tools. Use when the user pastes /ctrl-spc work <id> or /ctrl-spc artifact <id>, and to fetch one object when they paste /ctrl-spc workflow <id>, /ctrl-spc skill <id>, /ctrl-spc credential <id> or /ctrl-spc document <id>.';
 /** Home the skill files are written under. `CTRL_SPC_HOME` is the existing
  *  documented name for exactly this (docs/cli-surface-catalog.md), reused
  *  rather than renamed so one machine has one sandbox-home concept. */
@@ -77,6 +77,15 @@ export function installSkills(agents) {
  */
 const PROTOCOL_BODY = `Resolve a CTRL+SPC work item or artifact pasted as \`/ctrl-spc work <id>\` or \`/ctrl-spc artifact <id>\`, then follow the ctrl-spc working protocol:
+FETCH VERBS — \`workflow\`, \`skill\`, \`credential\` and \`document\` are NOT the working protocol. They name ONE object the user copied so they can use it in this conversation, and nothing below applies to them: no \`begin_work\`, no subagents, no context artifact, no question, no \`end_work\`. Fetch the object, use it for what the user asked, and answer.
+- \`/ctrl-spc workflow <id>\` — call \`read_workflow_library\` and use the workflow whose \`id\` matches, with the full body of each stage it holds. To RUN it on a work item, call \`start_workflow\` with that workflow id, then follow the working protocol below for the item. Report and stop when the user only asked to see it.
+- \`/ctrl-spc skill <id>\` — call \`get_skill\` with \`id\`. THE RESULT IS A DOCUMENT TO FOLLOW for the rest of this work, not reference material to summarise. Its supporting files come from \`read_skill_file\` with the same \`id\`.
+- \`/ctrl-spc credential <id>\` — call \`get_credential\` with \`id\`, then USE the value to do the work: a header, an environment variable, a command, local config. Never publish it: keep it out of your answer, comments, artifacts and questions, and name the credential instead.
+- \`/ctrl-spc document <id>\` — call \`get_document\` with \`id\`. One context document or one agent instruction, whole. It resolves either kind, so you do not need to know which the id names. To read a project's context as a whole instead, call \`get_project_context\`.
+Pass the pasted id as \`id\`. It names exactly one object, so \`org_id\` is never needed with it and a duplicate name cannot send you to the wrong one. Everything that follows is the WORK ITEM protocol:
 WORKFLOW AUTHORITY — when \`get_task.workflow.enabled\` is true, follow only its current stage, stored instructions, capabilities, requirements, and gate. Never infer or skip a stage. Persist each required artifact, then call \`hand_off_stage\` with the work item id and this request id, and stop: the next stage is worked by a fresh agent reading the record. It refuses a stage with unfinished steps and the last stage of the process, where you answer and stop instead. Review gates advance only after explicit user approval in the web app or conversation; requested changes stay in the same stage. Only final approval sets Done.
 HARD STOP — unclear novel feature (No workflow only): when \`workflow.enabled\` is false, after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\`, the exact question “What should I produce for this feature?”, \`answer_mode = multi_select\`, and options \`build\`, \`plan\`, \`spec\`, \`diagram\`, \`mock\`, and \`wireframe\`. Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question. The user may select one or more: build, plan, spec, diagram, mock, wireframe.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"