assent-cli 0.0.0-stage → 0.6.1

package/dist/usage.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = exports.LEGACY_COMMAND = exports.COMMAND = exports.VERSION = void 0;
+exports.usage = usage;
+exports.VERSION = "0.6.1";
+exports.COMMAND = "assent";
+exports.LEGACY_COMMAND = "ordia";
+function usage(command) {
+    return `Usage: ${command} <command> [options]
+${USAGE_BODY}`;
+}
+const USAGE_BODY = `
+  whoami                               Show the agent this key belongs to
+  run start [--summary s] [--max-minutes n]
+  run progress <run-uuid> --done n --total m [--label l]   Show progress on the phone (Live Activity)
+  run finish <run-uuid> (--exit-code n | --status ok|fail|deferred) [--summary s] [--log-file path] [--log-tail-bytes n]
+      [--task task-uuid] [--result-json path|-] [--done n] [--skipped n] [--needs-you n] [--failed n]   With --task, counts come from that task's item results
+      [--retry-at when]   Only with --status deferred
+      [--issue-reason needs_action|recovery_exhausted|deadline_at_risk --impact text --action-needed text]   Raises an action for the owner; not allowed with ok; at most 500 characters each
+  run defer <run-uuid> --retry-at when   Show the run as deferred until that time (for example after a usage limit)
+  ask --title t [--kind approve|todo|pay|login|code|reply] [--detail d] [--url u] [--draft text | --draft-file path|-]
+      [--action id:label[:primary|secondary|danger]]... [--item id:title[:unselected]]...
+      [--item-json path|-] [--recommend item-id]... [--reason item-id:text]... [--badge item-id:label[:tone]]... [--link item-id:label:url]... [--why text] [--field key:label[:type]:value]...
+      [--attach item-id:path]...
+      [--group key:title] [--conflict-on field-key]... [--total-of field-key] [--decline-action action-id]
+      [--rule-action name] [--target t]
+      [--due when] [--remind when] [--dedupe key] [--wait [--timeout seconds] [--interval seconds] [--no-pickup]]
+      [--question text] [--answer-type yes_no|choice|text|number|done] [--effort minutes] [--series key] [--idempotency-key uuid] [--allow-duplicate]
+  attach <path> [--name n]             Upload a file (pdf, png, jpeg, gif, webp, txt, md; at most 10 MB) and print its uuid, once the owner turns attachments on for this agent
+  answers                              Your answered asks that are not picked up yet
+  picked-up <task-uuid>                Mark an answer as acted on
+  task add --title t --why text [--detail d] [--url u] [--due when] [--remind when] [--dedupe key] [--project project-uuid [--track name]]
+      [--effort minutes] [--series key] [--idempotency-key uuid] [--allow-duplicate] [--parent ask-uuid --parent-item item-id]
+      --parent and --parent-item link the to-do to one item of your own ask: marking the to-do done marks that item done,
+      and resolving the item in the ask closes the to-do
+  task resolve <task-uuid> [--withdraw] [--note text]   Close your own ask once the work is done (or withdraw it); its reminders stop
+  task update <task-uuid> [--due when|none] [--remind when|none]   Only tasks this agent created
+  task get <task-uuid>
+  task item-result <task-uuid> <item-id> done|skipped|needs_you|failed [--reason r] [--url u]   Report each item as it finishes
+  task item-status <task-uuid> <item-id>   Prints go, held, withdrawn, not_selected or the recorded outcome for an item
+  note --title t (--content text | --content-file path | --content-file -) [--tag t]... [--run run-uuid]
+  note update <note-uuid> [--title t] [--content text | --content-file path | --content-file -] [--tag t]...
+  link --from type:uuid --to type:uuid [--relation produced|about|blocks|related]   types: note, task, run, agent
+  memory get                           Pinned memory notes shared with this agent
+  lock acquire <resource> [--ttl minutes] [--wait seconds] [--interval seconds]
+  lock release <resource> [--token t]
+  handoff (--to <agent name> | --to-uuid <agent uuid>) --title t [--detail d] [--run run-uuid]
+  handoffs                             Open hand-offs other agents gave you
+  handoffs done <task-uuid>            Mark a hand-off you received as done
+  project get <project-uuid>           Read a project this agent is linked to
+  project overview <project-uuid>      Progress, tracks, milestones, this week and overdue for a linked project
+  plan create --file path|- [--idempotency-key uuid]   JSON { title, summary?, tracks: [{key,title}], sessions: [{key,trackKey,title,dueAt,detail?,sessionMinutes?,habitKey?,url?}] }, at most 1000 sessions
+  plan get <plan-uuid>                 Read back a plan this agent created
+  plan sessions <plan-uuid> --file path|-   JSON { sessions: [{key, dueAt?, title?, detail?, status?: open|done|cancelled}] }, at most 500
+  rules check --action name [--target t] [--summary s]   Ask the person's standing rules first; exit 0 allow, 10 deny, 11 ask
+  rules list                           Standing rules that apply to this agent
+  rules add --deny --action pattern [--target pattern] [--reason r] [--expires 1d|7d|30d|none]   Agents can only add deny rules for themselves
+  rules remove <rule-uuid>             Remove a deny rule this agent added
+  hook pre-tool-use [--ask [--max-wait seconds]]   Read a PreToolUse hook event on stdin and print allow, deny or ask; always exits 0
+                                       --ask: for calls on the ask list, ask the person in Assent and wait (at most --max-wait, default 45); no answer or any error blocks the call
+  hook claude-code install|uninstall [--settings path] [--config path] [--yes]   Add or remove the Assent hook in Claude Code settings (default ~/.claude/settings.json), showing the change first
+  mcp                                  Run a stdio MCP server that forwards to the Assent MCP endpoint with this agent key
+
+--field types: text, money (GBP 42.00), date, datetime, number, score (8/10). Per-item fields and field tones (primary, tone) go through --item-json, a JSON array of items;
+--recommend, --reason, --badge (tones neutral, ok, warn, danger, note; at most 4) and --link (http or https; at most 4) then mark items by id.
+--attach uploads the file first, then puts its uuid on that item (at most 4 per item); an item-json item can also carry attachments: [{ "uuid": "..." }].
+--group puts separate asks from this agent with one key into one decision card; the key cannot contain a colon. --conflict-on (a field key, up to 4) flags members sharing that field's day or value, --total-of (a money field key) totals open members per currency, and --decline-action (an action id of the ask) is what "Keep one" answers the others with.
+
+when is a date and time: 2026-10-15T17:00 or 2026-10-15 17:00 (this computer's time zone), or with an offset like 2026-10-15T17:00:00+01:00.
+A bare date like 2026-10-15 means 09:00 that day in your Assent time zone, and prints a warning on stderr.
+--remind sets when the reminder push goes out. For a to-do (task add, or ask --kind todo) it is sent at that exact moment, even in quiet hours;
+for other asks a reminder that falls in quiet hours waits until they end. Without --remind, Assent reminds at the due time.
+
+--kind reply needs --draft (or --draft-file, a path or - for stdin, for multi-line text; one final line break is dropped), at most 4000 characters,
+and refuses them for other kinds. The person can edit the draft in Assent; the send action's answer.value is the final text to send (answers or task get).
+Default actions: send (primary) and skip; your own actions need one primary action, the send action. The draft is sent as written, without redaction.
+
+--rule-action (for example deploy:web or post) and --target (for example production or linkedin) name what an approve ask is about, so the person
+can answer Always or Never in Assent; a later ask that matches their standing rule comes back already answered. Allow rules only come from the person.
+Rule patterns use * as a wildcard and ignore case. hook pre-tool-use fails open: on any error it answers ask. ASSENT_HOOK_TIMEOUT_MS sets its timeout (default 3000).
+With --ask, calls matching hook.ask in the config file (default: git push, git reset --hard, rm -r, deploys, npm publish, terraform apply or destroy,
+kubectl delete, docker push) go to the person as an approve ask; it waits hook.waitSeconds or ASSENT_HOOK_WAIT_SECONDS (default 120) and blocks without an answer.
+
+--project files the new ask or task into a project the owner linked this agent to; --track puts it on that project track (for example "Weekly habits").
+ask, task add, note and handoff link the new item to --run, or to $ASSENT_RUN_UUID, as produced by that run.
+
+Every command prints JSON; --get <field> prints one field instead.
+Config: ASSENT_AGENT_KEY, and ASSENT_API_URL to use another server, or ASSENT_CONFIG or ~/.assent/config.json with {"agentKey": "oak_..."}. ASSENT_TIMEOUT_MS sets the request timeout (default 10000).
+Exit codes: 0 ok, 1 error, 2 usage, 3 conflict, lock held or expired, 4 not found, 5 not configured or unauthorised, 6 wait timed out, 10 rule says deny, 11 no rule (ask), 69 Assent unreachable.`;
+exports.USAGE = usage(exports.COMMAND);

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "assent-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "description": "Assent command line for agents: asks, runs, notes, tasks, locks, rules and hand-offs",
+  "license": "UNLICENSED",
+  "bin": { "assent-cli": "dist/bin.js", "assent": "dist/bin.js", "ordia": "dist/bin.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.13",
+    "@types/node": "^20.16.10",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.5.4"
+  }
+}