@constraint/cli 0.3.7 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constraint/cli",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Install, publish, and report Agent Skills with Constraint",
   "type": "module",
   "bin": {

package/skills/constraint-skills/SKILL.md

@@ -1,23 +1,25 @@
 ---
 name: constraint-skills
-description: Operate governed Agent Skills with the Constraint terminal CLI and report their invocations. Use when an agent needs to authenticate or diagnose Constraint access; configure agents; discover upload domains; inspect, install, update, or upload skills; query run history; or invoke any skill installed from or governed by Constraint.
+description: Operate governed Agent Skills with the Constraint terminal CLI. Use when an agent needs to authenticate or diagnose Constraint access; discover upload domains; inspect, install, update, or upload skills; review run history; or report a session transcript when the user asks to put skill work on the record.
 ---
 
 # Constraint Skills
 
-Use the `constraint` command for organization-authorized skills. Do not edit its config, lockfiles, instruction blocks, installation receipts, or authorization tokens directly.
+Use the `constraint` command for organization-authorized skills. Do not edit its
+config, lockfiles, installation receipts, or authorization tokens directly.
 
 ## Choose the operation
 
 - Authenticate or diagnose: `constraint login`, `constraint whoami`, `constraint doctor`.
-- Configure agents: `constraint setup`.
 - Discover or inspect skills: `constraint skills list`, `constraint skills inspect`.
 - Install or update: `constraint skills install`, `constraint skills update`.
 - Discover upload destinations: `constraint skills domains --json`.
 - Upload a local skill folder: `constraint skills upload`.
+- Report a session: `constraint report`.
 - Review runs: `constraint skills run list`, `constraint skills run get`.
 
-Read [references/commands.md](references/commands.md) before constructing flags or handling a less common operation.
+Read [references/commands.md](references/commands.md) before constructing flags
+or handling a less common operation.
 
 ## Upload skills
 
@@ -27,7 +29,9 @@ Upload the skill directory, not an individual `SKILL.md`. Before every upload, r
 constraint skills domains --json
 ```
 
-Use one returned `slug` exactly as `--domain`. Never guess a slug from a display name or reuse a domain from another organization. If multiple destinations are valid and ownership is unclear, ask the user.
+Use one returned `slug` exactly as `--domain`. Never guess a slug from a display
+name or reuse a domain from another organization. If multiple destinations are
+valid and ownership is unclear, ask the user.
 
 ```bash
 constraint skills upload <skill-directory> --domain <returned-slug>
@@ -35,33 +39,29 @@ constraint skills upload <skill-directory> --domain <returned-slug>
 
 ## Install skills
 
-Choose the target agent and scope explicitly. Prefer `--project`; use `--global` only when the user wants the skill across projects. Prefer managed links and use `--copy` only when independent files are required. Never overwrite locally edited installed skills.
+Choose the target agent and scope explicitly. Prefer `--project`; use
+`--global` only when the user wants the skill across projects. Prefer managed
+links and use `--copy` only when independent files are required. Never
+overwrite locally edited installed skills.
 
-## Start a run
+## Report a run
 
-Immediately after selecting and loading a governed skill, run:
+A run is the posting of a transcript in which a skill was invoked, and the user
+drives it: report only when the user asks to put a session on the record. Never
+report automatically or unprompted.
 
-```bash
-constraint skills run start <skill-name> --client <client> --session <session-id>
-```
-
-Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or `claude-code`. Use the current client session identifier. Retain the exact run ID printed by the command. If one session invokes multiple skills, start and retain a distinct run ID for each invocation.
-
-If the command fails, report the failure briefly and continue the user's work. Do not fabricate a run ID.
-
-## Complete a run
-
-After finishing the governed skill's work and before ending the response, locate the current session's real JSON or JSONL transcript file and run:
+When asked, locate the current session's real JSON or JSONL transcript file and run:
 
 ```bash
-constraint skills run complete <run-id> <transcript-path>
+constraint report <transcript-path> --skill <skill-name>
 ```
 
-Pass the explicit local path. The CLI uploads the whole transcript file as it exists at that moment and completes only that run. Never create a replacement transcript, summarize it, pass a temporary file, or guess a path.
-
-For multiple invocations, complete each retained run separately. Overlapping full-session transcript prefixes are expected. If the transcript path cannot be determined, leave the run started and tell the user that reporting could not be completed.
-
-Do not run completion hooks, background flushes, or pending-run scans.
+Pass the explicit local path to the transcript as it exists at that moment.
+Use the invoked skill's frontmatter `name`. Client and session id are read
+from the transcript path; re-reporting the same session later supersedes the
+earlier report. Never create a replacement transcript, summarize it, copy it
+elsewhere first, or pass a temporary file. If the transcript path cannot be
+determined, say so instead of guessing.
 
 ## Work safely
 

package/skills/constraint-skills/references/commands.md

@@ -12,7 +12,7 @@ constraint setup
 constraint doctor
 ```
 
-`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, then separately presents the managed global-instruction change and this skill's global installation destinations. It never replaces unrelated instructions.
+`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code and installs this skill globally. It never touches instruction files.
 
 ## Discover, inspect, install, and update
 
@@ -40,11 +40,11 @@ constraint skills upload <skill-directory> --domain <returned-slug>
 
 `skills domains` returns only domains where the authenticated user can manage skills. JSON objects contain the exact `slug`, display `name`, and `description`. Discover first and pass one returned slug. Ask the user when multiple domains fit and ownership is unclear.
 
-## Start, complete, and review runs
+## Report and review runs
 
 ```bash
-constraint skills run start <skill> --client codex --session <stable-session-id>
-constraint skills run complete <run-id> <actual-transcript-path>
+constraint report <actual-transcript-path> --skill <skill-name>
+constraint report <actual-transcript-path> --skill <skill-name> --client codex --session <id>
 
 constraint skills run list
 constraint skills run list --team <domain> --user <workos-user-id> --skill <skill>
@@ -52,6 +52,12 @@ constraint skills run get <run-id>
 constraint skills run get <run-id> --raw
 ```
 
+`report` is user-driven: run it only when the user asks to put a session on the
+record. Client and session id are read from the transcript path itself (Claude
+Code project transcripts and Codex rollouts are named by session id);
+`--client`/`--session` are only needed for files outside those locations.
+Re-reporting the same session supersedes the earlier report.
+
 Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.
 
 `run get` never prints a transcript to stdout: it writes the run JSON (or the
@@ -67,4 +73,4 @@ Global flags: `--json`, `--quiet`, `--no-color`, `--help`, and `--version`. Inst
 - Setup uncertainty: run `constraint doctor`.
 - Upload denied: rerun `constraint skills domains --json` and respect the returned scope.
 - Install conflict: preserve local edits.
-- Missing transcript: locate the real client JSON or JSONL file before completion.
+- Missing transcript: locate the real client JSON or JSONL file before reporting; if it cannot be found, tell the user instead of guessing.

package/src/cli.js

@@ -20,7 +20,6 @@ import {
   taskSpinner,
 } from './prompts.js';
 import {
-  applyInstructionSetup,
   installCompanionSkill,
   setupPlan,
   setupStatus,
@@ -36,7 +35,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.7';
+const VERSION = '0.4.1';
 
 const HELP = `Constraint Skills CLI
 
@@ -54,8 +53,7 @@ Usage:
                            [--copy] [--yes]
   constraint skills update --all [--agent <agent>]... [--project|--global] [--yes]
   constraint skills upload <path> --domain <domain>
-  constraint skills run start <skill> --client <client> --session <session-id>
-  constraint skills run complete <run-id> <transcript-path>
+  constraint report <transcript-path> --skill <skill> [--client <client>] [--session <id>]
   constraint skills run list [--team <team>]... [--user <user>]... [--skill <skill>]...
   constraint skills run get <run-id>... [--raw] [--output <path>]  (always writes a file, prints summary + path)
 
@@ -250,30 +248,17 @@ async function setupCommand(args, out) {
   if (dryRun) {
     out.data(plans.map((plan) => ({
       agent: plan.agent,
-      instructions: {
-        path: plan.instructions.path,
-        action: plan.instructions.changed ? 'update' : 'current',
-        content: plan.instructions.content,
-      },
       skill: { path: plan.skill.path, scope: 'global', action: plan.skill.action },
     })));
     return;
   }
-  const hasInstructionChanges = plans.some((plan) => plan.instructions.changed);
   const hasSkillChanges = plans.some((plan) => plan.skill.action !== 'current');
-  if (!useUi && !yes && (hasInstructionChanges || hasSkillChanges)) {
+  if (!useUi && !yes && hasSkillChanges) {
     throw new Error('Non-interactive setup has pending changes. Pass --yes or use --dry-run.');
   }
 
-  let configureInstructions = true;
   let installSkill = true;
   if (useUi) {
-    note(
-      plans.map((plan) => `${humanize(plan.agent)}\n${plan.instructions.path}\n${plan.instructions.changed ? 'Managed block will be added or updated' : 'Already configured'}`).join('\n\n'),
-      '1. Configure agent instructions',
-    );
-    configureInstructions = !hasInstructionChanges || yes || await confirmPlan('Apply these instruction changes?');
-
     note(
       [
         'Skill: constraint-skills',
@@ -285,20 +270,12 @@ async function setupCommand(args, out) {
           '',
         ]),
       ].join('\n').trim(),
-      '2. Install Constraint Skills',
+      'Install Constraint Skills',
     );
     installSkill = !hasSkillChanges || yes || await confirmPlan(`Install globally for ${agents.map(humanize).join(' and ')}?`);
   }
 
-  const result = { instructions: [], skill: [] };
-  if (configureInstructions) {
-    const spinner = taskSpinner(useUi && hasInstructionChanges);
-    for (const plan of plans) {
-      spinner.message(`Configuring ${humanize(plan.agent)} instructions`);
-      result.instructions.push(await applyInstructionSetup(plan.agent));
-    }
-    spinner.stop('Agent instructions configured.');
-  }
+  const result = { skill: [] };
   if (installSkill) {
     const spinner = taskSpinner(useUi && hasSkillChanges);
     for (const plan of plans) {
@@ -310,7 +287,6 @@ async function setupCommand(args, out) {
   if (useUi) {
     finish([
       'Setup complete.',
-      `Instructions: ${configureInstructions ? `${agents.length} configured` : 'skipped'}`,
       `Skill: ${installSkill ? `installed for ${agents.map(humanize).join(' and ')}` : 'skipped'}`,
     ].join('\n'));
   } else out.data(result);
@@ -471,31 +447,55 @@ async function uploadCommand(args, config, out) {
   out.data({ skill_id: detail.skill_id, slug: detail.slug, domain: detail.domain, version: detail.version.version });
 }
 
-async function runStart(args, config, out) {
-  const client = takeOption(args, '--client');
-  const session = takeOption(args, '--session');
-  rejectUnknown(args);
-  if (args.length !== 1 || !client || !session) {
-    throw new Error('Usage: constraint skills run start <skill> --client <client> --session <session-id>');
+// A run is the posting of a transcript in which a skill was invoked. The user
+// drives reporting: one command, after the session, with the finished
+// transcript. Client and session id come straight from the transcript path —
+// agent clients keep sessions at well-known locations named by session id.
+export function transcriptIdentity(absolute) {
+  const basename = path.basename(absolute);
+  const stem = basename.replace(/\.(jsonl?|json)$/i, '');
+  const uuid = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (absolute.includes(`${path.sep}.codex${path.sep}sessions${path.sep}`) || stem.startsWith('rollout-')) {
+    const match = stem.match(uuid);
+    return { client: 'codex', session: match ? match[0] : stem };
   }
-  const run = await apiRequest(config, '/skill-runs', {
-    method: 'POST',
-    ...jsonRequest({ skill: args[0], client, session_id: session }),
-  });
-  if (out.json) out.data(run);
-  else out.line(run.run_id);
+  if (absolute.includes(`${path.sep}.claude${path.sep}projects${path.sep}`) || uuid.test(stem)) {
+    const match = stem.match(uuid);
+    return { client: 'claude-code', session: match ? match[0] : stem };
+  }
+  return { client: null, session: null };
 }
 
-async function runComplete(args, config, out) {
+async function reportCommand(args, config, out) {
+  const skill = takeOption(args, '--skill');
+  const client = takeOption(args, '--client');
+  const session = takeOption(args, '--session');
   rejectUnknown(args);
-  if (args.length !== 2) throw new Error('Usage: constraint skills run complete <run-id> <transcript-path>');
-  const transcript = await readTranscript(args[1]);
-  const run = await apiRequest(config, `/skill-runs/${encodeURIComponent(args[0])}/complete`, {
+  if (args.length !== 1 || !skill) {
+    throw new Error('Usage: constraint report <transcript-path> --skill <skill> [--client <client>] [--session <session-id>]');
+  }
+  const transcript = await readTranscript(args[0]);
+  const identity = transcriptIdentity(transcript.absolute);
+  const resolvedClient = client || identity.client;
+  const resolvedSession = session || identity.session;
+  if (!resolvedClient || !resolvedSession) {
+    throw new Error('Could not tell the client and session from this path. Pass --client and --session.');
+  }
+  const query = new URLSearchParams({ skill, client: resolvedClient, session: resolvedSession });
+  const run = await apiRequest(config, `/skill-reports?${query.toString()}`, {
     method: 'POST',
     headers: { 'Content-Type': mediaType(transcript.absolute), 'X-Transcript-Filename': transcript.filename },
     body: transcript.content,
   });
-  out.data(run);
+  out.data({
+    run_id: run.run_id,
+    skill: run.skill_slug,
+    version: run.skill_version,
+    state: run.state,
+    client: run.client,
+    session: run.client_session_id,
+    transcript_bytes: run.transcript_size,
+  });
 }
 
 async function runList(args, config, out) {
@@ -560,11 +560,9 @@ async function runGet(args, config, out) {
 
 async function runCommand(args, config, out) {
   const command = args.shift();
-  if (command === 'start') return runStart(args, config, out);
-  if (command === 'complete') return runComplete(args, config, out);
   if (command === 'list') return runList(args, config, out);
   if (command === 'get') return runGet(args, config, out);
-  throw new Error('Expected skills run start, complete, list, or get.');
+  throw new Error('Expected skills run list or get. Post a transcript with constraint report.');
 }
 
 async function skillsCommand(args, config, out) {
@@ -597,6 +595,7 @@ export async function main(argv) {
   if (['login', 'logout', 'whoami'].includes(command)) return authCommand(command, args, config, out);
   if (command === 'setup') return setupCommand(args, out);
   if (command === 'doctor') return doctorCommand(args, config, out);
+  if (command === 'report') return reportCommand(args, config, out);
   if (command === 'skills') return skillsCommand(args, config, out);
   throw new Error(`Unknown command: ${command}`);
 }

package/src/paths.js

@@ -28,18 +28,15 @@ export function agentPaths(agent, { scope = 'global', projectRoot = process.cwd(
   const selected = normalizeAgent(agent);
   if (scope === 'project') {
     if (selected === 'codex') {
-      return { skills: path.join(projectRoot, '.agents', 'skills'), instructions: null };
+      return { skills: path.join(projectRoot, '.agents', 'skills') };
     }
-    return { skills: path.join(projectRoot, '.claude', 'skills'), instructions: null };
+    return { skills: path.join(projectRoot, '.claude', 'skills') };
   }
   if (selected === 'codex') {
     const root = process.env.CODEX_HOME ? expandPath(process.env.CODEX_HOME) : path.join(os.homedir(), '.codex');
-    return { instructions: path.join(root, 'AGENTS.md'), skills: path.join(root, 'skills') };
+    return { skills: path.join(root, 'skills') };
   }
-  return {
-    instructions: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
-    skills: path.join(os.homedir(), '.claude', 'skills'),
-  };
+  return { skills: path.join(os.homedir(), '.claude', 'skills') };
 }
 
 async function exists(candidate) {

package/src/setup.js

@@ -6,37 +6,6 @@ import { loadConfig, saveConfig } from './config.js';
 import { packageDigest, readSkillDirectory, writeSkillDirectory } from './files.js';
 import { agentPaths, normalizeAgent } from './paths.js';
 
-export const BLOCK_START = '<!-- constraint-skills:start -->';
-export const BLOCK_END = '<!-- constraint-skills:end -->';
-
-const BLOCK = `${BLOCK_START}
-## Constraint Skills
-
-When using the Constraint CLI or invoking any installed Agent Skill, load and
-follow the global \`constraint-skills\` companion skill. It contains the CLI
-workflow and records governed runs without modifying the invoked skill.
-${BLOCK_END}`;
-
-export function mergeInstructionBlock(existing) {
-  const start = existing.indexOf(BLOCK_START);
-  const end = existing.indexOf(BLOCK_END);
-  if ((start >= 0) !== (end >= 0)) {
-    throw new Error('The existing Constraint Skills instruction block is incomplete; fix it before running setup.');
-  }
-  if (start >= 0 && end >= start) {
-    return `${existing.slice(0, start)}${BLOCK}${existing.slice(end + BLOCK_END.length)}`;
-  }
-  const separator = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
-  return `${existing}${separator}${BLOCK}\n`;
-}
-
-async function writeInstructions(file, content, mode) {
-  await fs.mkdir(path.dirname(file), { recursive: true });
-  const staging = `${file}.constraint-${process.pid}`;
-  await fs.writeFile(staging, content, { mode });
-  await fs.rename(staging, file);
-}
-
 async function companionFiles() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   return readSkillDirectory(path.resolve(here, '..', 'skills', 'constraint-skills'));
@@ -49,19 +18,6 @@ export function expectedCompanionHash(config, selected, currentHash) {
   return currentHash && recorded.includes(currentHash) ? currentHash : null;
 }
 
-async function instructionPlan(selected, paths) {
-  let existing = '';
-  let mode = 0o644;
-  try {
-    existing = await fs.readFile(paths.instructions, 'utf8');
-    mode = (await fs.stat(paths.instructions)).mode & 0o777;
-  } catch (error) {
-    if (error && error.code !== 'ENOENT') throw error;
-  }
-  const content = mergeInstructionBlock(existing);
-  return { path: paths.instructions, changed: content !== existing, content, mode };
-}
-
 async function skillPlan(selected, paths) {
   const files = await companionFiles();
   const bundledHash = packageDigest(files);
@@ -89,7 +45,6 @@ export async function setupPlan(agent) {
   const paths = agentPaths(selected);
   return {
     agent: selected,
-    instructions: await instructionPlan(selected, paths),
     skill: await skillPlan(selected, paths),
   };
 }
@@ -100,15 +55,6 @@ async function recordConfiguredAgent(selected, config = null) {
   await saveConfig(next);
 }
 
-export async function applyInstructionSetup(agent) {
-  const selected = normalizeAgent(agent);
-  const paths = agentPaths(selected);
-  const plan = await instructionPlan(selected, paths);
-  if (plan.changed) await writeInstructions(plan.path, plan.content, plan.mode);
-  await recordConfiguredAgent(selected);
-  return { agent: selected, path: plan.path, changed: plan.changed, applied: true };
-}
-
 export async function installCompanionSkill(agent) {
   const selected = normalizeAgent(agent);
   const paths = agentPaths(selected);
@@ -127,42 +73,25 @@ export async function installCompanionSkill(agent) {
 
 export async function setupAgent(agent, {
   dryRun = false,
-  yes = false,
-  confirmChange = async () => false,
   output = console.log,
-  instructions = true,
-  skill = true,
 } = {}) {
   const selected = normalizeAgent(agent);
   const plan = await setupPlan(selected);
-  output(`${selected}: ${plan.instructions.path}`);
   if (dryRun) {
-    if (instructions) output(plan.instructions.content);
-    if (skill) output(`Install constraint-skills globally at ${plan.skill.path} (${plan.skill.action}).`);
-    return { agent: selected, instructions: plan.instructions, skill: plan.skill, applied: false };
-  }
-  let instructionResult = null;
-  let skillResult = null;
-  if (instructions) {
-    const approved = !plan.instructions.changed || yes || await confirmChange(
-      `Add the Constraint Skills block to ${plan.instructions.path}?`,
-    );
-    if (approved) instructionResult = await applyInstructionSetup(selected);
+    output(`Install constraint-skills globally at ${plan.skill.path} (${plan.skill.action}).`);
+    return { agent: selected, skill: plan.skill, applied: false };
   }
-  if (skill) skillResult = await installCompanionSkill(selected);
-  return { agent: selected, instructions: instructionResult, skill: skillResult, applied: true };
+  const skillResult = await installCompanionSkill(selected);
+  return { agent: selected, skill: skillResult, applied: true };
 }
 
 export async function setupStatus(agent) {
   const selected = normalizeAgent(agent);
   const paths = agentPaths(selected);
   try {
-    const [instructions, skill] = await Promise.all([
-      fs.readFile(paths.instructions, 'utf8'),
-      fs.stat(path.join(paths.skills, 'constraint-skills', 'SKILL.md')),
-    ]);
-    return { agent: selected, instructions: instructions.includes(BLOCK_START), skill: skill.isFile() };
+    const skill = await fs.stat(path.join(paths.skills, 'constraint-skills', 'SKILL.md'));
+    return { agent: selected, skill: skill.isFile() };
   } catch {
-    return { agent: selected, instructions: false, skill: false };
+    return { agent: selected, skill: false };
   }
 }