docket-agent 0.1.0

package/src/commands/mcp.js

@@ -0,0 +1,187 @@
+// MCP server (stdio, newline-delimited JSON-RPC) so agents use docket natively:
+// look up a loop's context, check the warrant before acting, leave record entries.
+// Zero dependencies — the protocol surface we need is small.
+
+import readline from 'node:readline';
+import { parseArgs } from '../lib/args.js';
+import { requireDocketDir, listLoops, loadLoop, loopExists, loopNames, ACTIONS } from '../lib/loop.js';
+import { checkWarrant } from '../lib/warrant.js';
+import { appendRecord, collectRecordFields, recordCheck } from '../lib/record.js';
+import { renderLoop } from '../lib/compile.js';
+import { VERSION } from '../lib/pkg.js';
+
+const TOOLS = [
+  {
+    name: 'docket_list_loops',
+    description:
+      'List the loops the human has defined. Each loop is one recurring task with brief, procedure, warrant, record, and reserved layers.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'docket_loop_context',
+    description:
+      'Get the full context for a loop before starting work on it: what you must know, how the work is done, what you may do on your own, where you must stop, and what evidence you owe. Call this FIRST, before doing the task.',
+    inputSchema: {
+      type: 'object',
+      properties: { loop: { type: 'string', description: 'loop name' } },
+      required: ['loop'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'docket_warrant_check',
+    description:
+      'Check whether an action is covered by the warrant of a loop BEFORE doing it. Returns allow, ask, or deny. "ask" means stop and get human approval; "deny" means never. The check itself is written to the record. Call this before any read/draft/change/send that could matter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        loop: { type: 'string', description: 'loop name' },
+        action: { type: 'string', enum: ACTIONS, description: 'what kind of act this is' },
+        target: {
+          type: 'string',
+          description: 'what the action touches, in plain words (e.g. "appeal email to the insurer")',
+        },
+      },
+      required: ['loop', 'action', 'target'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'docket_record',
+    description:
+      'Add to the record: what you saw, what you did, what you skipped or left alone, and where you stopped. The record is hash-chained and verifiable. Write to it whenever you finish or stop work on a loop.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        loop: { type: 'string', description: 'loop name' },
+        saw: { type: 'string', description: 'sources and state you consulted' },
+        did: { type: 'string', description: 'what you actually did' },
+        skipped: { type: 'string', description: 'what you deliberately left alone' },
+        stopped: { type: 'string', description: 'where and why you stopped' },
+        note: { type: 'string', description: 'anything else a human should be able to trust' },
+      },
+      required: ['loop'],
+      additionalProperties: false,
+    },
+  },
+];
+
+function textResult(text, isError = false) {
+  return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+
+export function handleToolCall(docketDir, name, args = {}) {
+  switch (name) {
+    case 'docket_list_loops': {
+      const loops = listLoops(docketDir);
+      if (!loops.length) return textResult('No loops defined yet.');
+      return textResult(loops.map((l) => `${l.name}: ${l.description}`).join('\n'));
+    }
+    case 'docket_loop_context': {
+      const loop = loadLoop(docketDir, args.loop);
+      return textResult(renderLoop(loop));
+    }
+    case 'docket_warrant_check': {
+      const loop = loadLoop(docketDir, args.loop);
+      const result = checkWarrant(loop, args.action, args.target);
+      recordCheck(docketDir, loop.name, args.action, args.target, result, { via: 'mcp' });
+      const instruction = {
+        allow: 'Proceed.',
+        ask: 'STOP. Do not do this yet — tell the human what you want to do and why, and wait for approval.',
+        deny: 'Do NOT do this, even if asked again in this session. It is outside the loop entirely.',
+      }[result.verdict];
+      return textResult(
+        `verdict: ${result.verdict}\nrule: ${result.rule}\n${result.reason}\n${instruction}`
+      );
+    }
+    case 'docket_record': {
+      if (!loopExists(docketDir, args.loop)) {
+        return textResult(
+          `no loop named "${args.loop}" — have: ${loopNames(docketDir).join(', ') || '(none)'}`,
+          true
+        );
+      }
+      const { fields, dropped } = collectRecordFields(args);
+      if (dropped.length) {
+        return textResult(`these fields were empty, refusing to lose evidence: ${dropped.join(', ')}`, true);
+      }
+      if (!Object.keys(fields).length) {
+        return textResult('a record entry needs at least one of: saw, did, skipped, stopped, note', true);
+      }
+      const entry = appendRecord(docketDir, { loop: args.loop, kind: 'note', via: 'mcp', ...fields });
+      return textResult(`record #${entry.seq} appended (${entry.hash.slice(0, 23)}…)`);
+    }
+    default:
+      return textResult(`unknown tool: ${name}`, true);
+  }
+}
+
+export function cmdMcp(argv = []) {
+  // MCP hosts often spawn servers with cwd '/' — resolve the project from
+  // --dir (or DOCKET_DIR) so the config can say where the loops live, and
+  // never die before initialize: a server that crashes on startup surfaces
+  // as an opaque "disconnected" in the client.
+  const { flags } = parseArgs(argv);
+  const startDir = flags.dir ?? process.env.DOCKET_DIR ?? process.cwd();
+  let docketDir = null;
+  let startupError = null;
+  try {
+    docketDir = requireDocketDir(startDir);
+  } catch (err) {
+    startupError = `${err.message} (searched upward from ${startDir}; pass --dir <project> or set DOCKET_DIR)`;
+  }
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
+
+  rl.on('line', (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+      return;
+    }
+    const { id, method, params } = msg;
+    const reply = (result) => id !== undefined && send({ jsonrpc: '2.0', id, result });
+    const fail = (code, message) =>
+      id !== undefined && send({ jsonrpc: '2.0', id, error: { code, message } });
+
+    try {
+      switch (method) {
+        case 'initialize':
+          reply({
+            protocolVersion: params?.protocolVersion ?? '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'docket', version: VERSION },
+          });
+          break;
+        case 'notifications/initialized':
+        case 'notifications/cancelled':
+          break; // notifications: no response
+        case 'ping':
+          reply({});
+          break;
+        case 'tools/list':
+          reply({ tools: TOOLS });
+          break;
+        case 'tools/call':
+          if (!docketDir) {
+            reply(textResult(startupError, true));
+            break;
+          }
+          reply(handleToolCall(docketDir, params?.name, params?.arguments ?? {}));
+          break;
+        default:
+          fail(-32601, `method not found: ${method}`);
+      }
+    } catch (err) {
+      if (id !== undefined) {
+        reply(textResult(String(err && err.message ? err.message : err), true));
+      }
+    }
+  });
+
+  // Keep the process alive until stdin closes.
+  return new Promise((resolve) => rl.on('close', () => resolve(0)));
+}

package/src/commands/new.js

@@ -0,0 +1,229 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline';
+import { parseArgs } from '../lib/args.js';
+import {
+  requireDocketDir,
+  loopFile,
+  parseLoop,
+  splitFrontmatter,
+  LoopError,
+  LOOP_NAME_RE,
+} from '../lib/loop.js';
+import { dumpYaml } from '../lib/yaml.js';
+import { bold, cyan, dim, green } from '../lib/ui.js';
+
+const TEMPLATES_DIR = path.join(fileURLToPath(new URL('.', import.meta.url)), '../../templates');
+
+export function listTemplates() {
+  return fs
+    .readdirSync(TEMPLATES_DIR)
+    .filter((f) => f.endsWith('.loop.md'))
+    .sort()
+    .map((f) => {
+      const text = fs.readFileSync(path.join(TEMPLATES_DIR, f), 'utf8');
+      const loop = parseLoop(text, { file: f });
+      return { name: loop.name, description: loop.description, file: path.join(TEMPLATES_DIR, f) };
+    });
+}
+
+export function cmdTemplates() {
+  console.log(bold('Starter loops') + dim(' — each is one recurring task, five layers, ready to edit\n'));
+  for (const t of listTemplates()) {
+    console.log(`  ${cyan(t.name.padEnd(20))} ${t.description}`);
+  }
+  console.log(dim('\nUse one:  docket new <name> --template <template>'));
+  return 0;
+}
+
+function scaffold({ name, description, brief, procedure, warrant, reserved, record }) {
+  const frontmatter = dumpYaml({
+    name,
+    description,
+    version: 1,
+    warrant,
+    reserved,
+    record,
+  });
+  return `---\n${frontmatter}---\n\n# Brief\n\n${brief}\n\n# Procedure\n\n${procedure}\n`;
+}
+
+const PLACEHOLDER = {
+  brief: `<!-- The context that changes the answer: the people involved, the history
+so far, hard constraints, standards, and decisions already made. Without
+this, the agent guesses. -->\n\n- TODO`,
+  procedure: `<!-- How this job is done properly. Which sources count, what finished
+looks like, and the known ways it goes wrong. -->\n\n1. TODO`,
+};
+
+function splitList(answer) {
+  return answer
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+async function interview(name) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  // Buffer lines that arrive while no question is pending — pasted blocks of
+  // prepared answers must feed successive questions, not vanish.
+  const buffered = [];
+  let waiter = null;
+  let closed = false;
+  rl.on('line', (line) => {
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w.resolve(line);
+    } else {
+      buffered.push(line);
+    }
+  });
+  rl.on('close', () => {
+    closed = true;
+    if (waiter) {
+      const err = new Error('interview aborted');
+      err.code = 'ABORT_ERR';
+      waiter.reject(err);
+    }
+  });
+  const readAnswer = () => {
+    if (buffered.length) return Promise.resolve(buffered.shift());
+    if (closed) {
+      const err = new Error('interview aborted');
+      err.code = 'ABORT_ERR';
+      return Promise.reject(err);
+    }
+    return new Promise((resolve, reject) => {
+      waiter = { resolve, reject };
+    });
+  };
+  const q = async (prompt, hint) => {
+    if (hint) console.log(dim(`  ${hint}`));
+    rl.setPrompt(`${prompt} `);
+    rl.prompt();
+    const a = await readAnswer();
+    console.log();
+    return a.trim();
+  };
+  console.log(
+    `\n${bold(`Five questions build the loop "${name}".`)}\n${dim(
+      'Unwritten answers get guessed at. Written answers get enforced.'
+    )}\n`
+  );
+
+  const brief = await q(
+    bold('1. What must the agent know before it starts?'),
+    'the context that changes the answer: people, history, constraints, standards, past decisions'
+  );
+  const procedure = await q(
+    bold('2. How is this work supposed to be done?'),
+    'sources that count, what done looks like, the known ways it goes wrong'
+  );
+  console.log(bold('3. What may it do without asking?') + dim('  (comma-separated; empty = ask first)'));
+  const read = splitList(await q('   read:'));
+  const draft = splitList(await q('   draft:'));
+  const change = splitList(await q('   change:'));
+  const send = splitList(await q('   send:'));
+  console.log(bold('4. Where does it have to stop?'));
+  const ask = splitList(await q('   always ask before:', 'comma-separated'));
+  const never = splitList(await q('   never, even with approval:', 'comma-separated'));
+  const reserved = splitList(
+    await q('   what stays human:', 'accounts, secrets, permissions, final sign-off')
+  );
+  const record = splitList(
+    await q(
+      bold('5. What evidence must it leave behind?'),
+      'e.g. sources consulted, what was drafted, what was skipped, where it stopped'
+    )
+  );
+  const description = await q(bold('One-line description of this loop:'));
+  rl.close();
+
+  return {
+    name,
+    description: description || `The ${name} loop.`,
+    brief: brief ? `- ${brief}` : PLACEHOLDER.brief,
+    procedure: procedure ? `1. ${procedure}` : PLACEHOLDER.procedure,
+    warrant: { read, draft, change, send, ask, never },
+    reserved,
+    record,
+  };
+}
+
+// Rename a template through the frontmatter layer, not blind text
+// substitution — and parseLoop's name-vs-filename check backstops it.
+function withName(templateText, name) {
+  const { frontmatter, body } = splitFrontmatter(templateText);
+  const renamed = frontmatter.replace(/^\s*name\s*:.*$/m, `name: ${name}`);
+  return `---\n${renamed}\n---\n${body}`;
+}
+
+export async function cmdNew(argv) {
+  const { flags, positional } = parseArgs(argv, { booleans: ['blank'] });
+  const name = positional[0];
+  if (!name) {
+    console.error('usage: docket new <name> [--template <template>] [--blank]');
+    return 1;
+  }
+  if (!LOOP_NAME_RE.test(name)) {
+    console.error('docket: loop names are lowercase letters, digits, and dashes');
+    return 1;
+  }
+  const docketDir = requireDocketDir();
+  const dest = loopFile(docketDir, name);
+  if (fs.existsSync(dest)) {
+    console.error(`docket: loop "${name}" already exists at ${dest}`);
+    return 1;
+  }
+
+  let content;
+  if (flags.template) {
+    const tpl = listTemplates().find((t) => t.name === flags.template);
+    if (!tpl) {
+      console.error(
+        `docket: no template "${flags.template}" — run \`docket templates\` to see them`
+      );
+      return 1;
+    }
+    content = withName(fs.readFileSync(tpl.file, 'utf8'), name);
+  } else if (!flags.blank && process.stdin.isTTY && process.stdout.isTTY) {
+    try {
+      content = scaffold(await interview(name));
+    } catch (err) {
+      if (err && (err.code === 'ABORT_ERR' || /abort/i.test(err.message ?? ''))) {
+        console.error('\ndocket: interview cancelled — nothing written');
+        return 1;
+      }
+      throw err;
+    }
+  } else {
+    content = scaffold({
+      name,
+      description: `TODO: one line on what the ${name} loop does.`,
+      brief: PLACEHOLDER.brief,
+      procedure: PLACEHOLDER.procedure,
+      warrant: { read: [], draft: [], change: [], send: [], ask: [], never: [] },
+      reserved: ['final approval'],
+      record: ['what it saw', 'what it did', 'what it left alone', 'where it stopped'],
+    });
+  }
+
+  // Validate before writing — a loop that can't be parsed can't protect anyone.
+  try {
+    parseLoop(content, { file: dest });
+  } catch (err) {
+    if (err instanceof LoopError) {
+      console.error(`docket: refusing to write an invalid loop: ${err.message}`);
+      return 1;
+    }
+    throw err;
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+  console.log(green('✓') + ` wrote ${path.relative(process.cwd(), dest)}`);
+  console.log(dim(`  edit it, then: docket show ${name} · docket check ${name} send "…" · docket compile --write`));
+  return 0;
+}

package/src/commands/record.js

@@ -0,0 +1,116 @@
+import { parseArgs } from '../lib/args.js';
+import { requireDocketDir, loopExists, loopNames } from '../lib/loop.js';
+import {
+  appendRecord,
+  collectRecordFields,
+  readRecords,
+  verifyRecord,
+  recordFile,
+} from '../lib/record.js';
+import { bold, cyan, dim, green, red, VERDICT_STYLE } from '../lib/ui.js';
+
+function formatEntry(e) {
+  const ts = dim(e.ts.replace('T', ' ').replace(/\.\d+Z$/, 'Z'));
+  const head = `${dim(`#${e.seq}`)} ${ts} ${cyan(e.loop)}`;
+  if (e.kind === 'check') {
+    const style = VERDICT_STYLE[e.verdict] ?? { color: (s) => s, badge: e.verdict };
+    return `${head} ${style.color(style.badge.toLowerCase())} ${e.action} → "${e.target}" ${dim(`(${e.rule})`)}`;
+  }
+  const parts = [];
+  if (e.saw) parts.push(`saw: ${e.saw}`);
+  if (e.did) parts.push(`did: ${e.did}`);
+  if (e.skipped) parts.push(`skipped: ${e.skipped}`);
+  if (e.stopped) parts.push(`stopped: ${e.stopped}`);
+  if (e.note) parts.push(e.note);
+  return `${head} ${parts.join(' · ') || dim('(empty note)')}`;
+}
+
+export function cmdRecord(argv) {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case 'add':
+      return recordAdd(rest);
+    case 'log':
+      return recordLog(rest);
+    case 'verify':
+      return recordVerify(rest);
+    default:
+      console.error('usage: docket record <add|log|verify>');
+      return 1;
+  }
+}
+
+function recordAdd(argv) {
+  const { flags, positional } = parseArgs(argv);
+  const loopName = positional[0];
+  if (!loopName) {
+    console.error(
+      'usage: docket record add <loop> [--saw ..] [--did ..] [--skipped ..] [--stopped ..] [--note ..]'
+    );
+    return 1;
+  }
+  const docketDir = requireDocketDir();
+  // Existence check by filename, deliberately not a full parse: a loop file
+  // with a frontmatter typo must not block the agent from leaving evidence.
+  if (!loopExists(docketDir, loopName)) {
+    const available = loopNames(docketDir);
+    console.error(
+      `docket: no loop named "${loopName}"${available.length ? ` — have: ${available.join(', ')}` : ''}`
+    );
+    return 1;
+  }
+  const { fields, dropped } = collectRecordFields(flags);
+  if (dropped.length) {
+    // A record entry that silently loses evidence is worse than an error.
+    console.error(
+      `docket: refusing to write — ${dropped.map((d) => `--${d}`).join(', ')} ` +
+        `${dropped.length === 1 ? 'has' : 'have'} no text (empty or missing value)`
+    );
+    return 1;
+  }
+  if (!Object.keys(fields).length) {
+    console.error('docket: a record entry with nothing in it proves nothing — pass --saw/--did/--skipped/--stopped/--note');
+    return 1;
+  }
+  const entry = appendRecord(docketDir, { loop: loopName, kind: 'note', via: 'cli', ...fields });
+  console.log(green('✓') + ` record #${entry.seq} ${dim(entry.hash.slice(0, 23) + '…')}`);
+  return 0;
+}
+
+function recordLog(argv) {
+  const { flags, positional } = parseArgs(argv);
+  const docketDir = requireDocketDir();
+  const loopName = positional[0];
+  const n = Number(flags.n ?? 20);
+  let entries = readRecords(docketDir);
+  if (loopName) entries = entries.filter((e) => e.loop === loopName);
+  if (!entries.length) {
+    console.log('no record entries yet');
+    return 0;
+  }
+  for (const e of entries.slice(-n)) console.log(formatEntry(e));
+  console.log(dim(`\n${entries.length} total · file: ${recordFile(docketDir)}`));
+  return 0;
+}
+
+function recordVerify(argv) {
+  const { flags } = parseArgs(argv);
+  const docketDir = requireDocketDir();
+  const result = verifyRecord(docketDir, {
+    expectHead: typeof flags.head === 'string' ? flags.head : undefined,
+  });
+  if (result.ok) {
+    console.log(
+      green('✓ chain intact') +
+        ` — ${result.count} entr${result.count === 1 ? 'y' : 'ies'}, every entry commits to the one before it`
+    );
+    console.log(dim(`  head: ${result.head}`));
+    console.log(
+      dim('  pin this head somewhere the log can\'t reach, then: docket record verify --head <hash>')
+    );
+    return 0;
+  }
+  console.error(red(bold('✗ chain broken')) + ` at entry ${result.brokenAt}: ${result.problem}`);
+  console.error(dim('  a record that can be edited quietly is not a record'));
+  return 1;
+}

package/src/lib/args.js

@@ -0,0 +1,36 @@
+// Dependency-free flag parsing: `--key value`, `--key=value`, boolean flags.
+//
+// Only flags declared in `booleans` are ever treated as boolean — everything
+// else consumes the next token as its value even if that token starts with
+// `--`. Guessing from the token's shape silently drops user data (a --note
+// whose text begins with a dash would vanish from the record).
+
+export function parseArgs(argv, { booleans = [] } = {}) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        const key = arg.slice(2);
+        if (booleans.includes(key)) {
+          flags[key] = true;
+        } else if (i + 1 < argv.length) {
+          flags[key] = argv[++i];
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}