@dench.com/cli 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# Dench CLI
+
+Agent-facing CLI for the Dench agent workspace.
+
+## Usage
+
+Run without installing:
+
+```bash
+npx -y dench-cli login --name "AI Agent - Billing Repo"
+```
+
+Or install globally:
+
+```bash
+npm install -g dench-cli
+dench login --name "AI Agent - Billing Repo"
+```
+
+`--kind` accepts any string. Suggested values: `claude_code`, `codex`, `cursor`,
+`hermes`, `openclaw`, or any custom kind such as `aider`, `goose`, or
+`some_custom_agent`. Defaults to `other` when omitted. Values are normalized
+to lowercase snake_case before send (e.g. `--kind "Claude Code"` becomes
+`claude_code`).
+
+The default host is `https://dench.dev`.
+
+The smooth setup flow is:
+
+1. Run `dench login --name "AI Agent - Billing Repo"` once.
+2. Let the CLI open the approval link. If it cannot, ask the human to open the
+   printed link and confirm the email/workspace. Use `--no-open` to print the
+   link without opening it.
+3. Run `dench status --mine --json` and `dench tasks --json` to verify setup.
+
+The CLI selects the approved session for later commands automatically.
+Setup is complete after approval, both verification commands work, and you know
+which Dench agent/session is selected.
+
+Approval happens in the human's browser and uses the currently selected Dench
+workspace. The human should switch to the intended workspace before approving.
+The CLI opens the approval link automatically when possible. If opening fails,
+use the printed link manually.
+
+If multiple sessions already exist, do not log in again to fix ambiguity and do
+not silently guess from the newest timestamp, agent name, or kind. List sessions
+and ask the human which exact session to use:
+
+```bash
+dench sessions
+dench use <session-key-or-workspace-slug>
+```
+
+Use a human-readable `DENCH_SESSION_KEY` at login time only for long-lived
+agents or when the human asks for a stable identity:
+
+```bash
+DENCH_SESSION_KEY=billing-repo-agent dench login --name "AI Agent - Billing Repo"
+DENCH_SESSION_KEY=billing-repo-agent dench status --mine --json
+```
+
+Do not set `DENCH_SESSION_KEY` to values like `auto:...` or `explicit:...`.
+Those are internal scopes shown by `dench sessions`; select them with
+`dench use <session-key-or-workspace-slug>` instead.
+
+`dench logout` removes only the current selected session for this local agent
+context. Other saved sessions can still be reused by future chats. To remove the
+wrong local session, run `dench logout --session <session-key>`. Use
+`dench logout --all` only when you want to clear every local Dench session.
+
+Do not create or edit local agent memory files during setup. Use Dench logs for
+meaningful progress, and use Dench memory only when the human asks or when
+saving a stable workspace fact.
+
+Do not create, claim, or log a setup task by default. Only create or claim a
+task if the human assigns work, an open matching task exists, or coordination
+benefits from creating one. For ad-hoc requests, work directly and only log
+meaningful work.
+
+Use `dench context` when you need to know who you are, which workspace you are
+using, assigned tasks, pending approvals you requested, connected apps, and the
+best next commands. Add `--json` for structured output.
+
+## Billing
+
+Fresh workspaces verify a card for abuse prevention before starter credits are
+issued. The card verification does not charge the human. New workspaces receive
+$5 in starter AI credits, with automatic overage disabled by default.
+
+Check AI credits:
+
+```bash
+dench billing status --json
+```
+
+Create a top-up link for the human to pay:
+
+```bash
+dench billing topup --amount 5 --json
+```
+
+Do not claim the top-up succeeded until Stripe returns success or
+`dench billing status --json` shows the new credits.
+
+## External Apps
+
+List connected apps:
+
+```bash
+dench apps --json
+```
+
+`dench apps` is an alias for `dench tool status` with no toolkit.
+
+Other tool commands:
+
+```bash
+dench tool status [toolkit] --json
+dench tool connect <toolkit> --json
+dench tool search "list recent gmail emails" --toolkit gmail
+dench tool run <composio_tool_slug> --args '{"key":"value"}' --json
+```
+
+Start with compact `dench tool search` output. It lists ranked tools with slug,
+toolkit, connection status, and read-only/approval hints. Add `--json` only when
+you need full raw schemas or exact argument details.
+
+Run clear read-only information retrieval tools through Dench without requesting
+manual approval first. This includes slugs containing `FETCH`, `GET`, `LIST`,
+`SEARCH`, `READ`, or `FIND`, such as `GMAIL_FETCH_EMAILS`:
+
+```bash
+dench tool run GMAIL_FETCH_EMAILS --args '{"max_results":10}' --json
+```
+
+Dench enforces the final policy and returns `requiresApproval` when approval is
+needed.
+
+For Gmail and other email tools, summarize safely. Prefer metadata and snippets.
+Do not repeat OTP codes, security codes, passwords, tokens, API keys, or secrets
+from email bodies. Non-JSON `tool run` display redacts likely sensitive codes;
+`--json` preserves the raw provider response for cases that need it.
+
+Run `dench tool --help` or `dench apps --help` for command help.
+
+For staging:
+
+```bash
+dench login --staging
+dench login --host https://workspace-staging.dench.com
+```

package/agentKind.ts

@@ -0,0 +1,58 @@
+/**
+ * Mirror of `convex/lib/agentKind.ts` for the CLI. The published package
+ * cannot import from the Convex backend, so the normalization logic lives
+ * here as well. Keep both copies in lockstep.
+ */
+
+export const KNOWN_AGENT_KINDS = [
+  "claude_code",
+  "codex",
+  "cursor",
+  "hermes",
+  "openclaw",
+  "other",
+] as const;
+
+export type KnownAgentKind = (typeof KNOWN_AGENT_KINDS)[number];
+
+export const KNOWN_AGENT_KIND_SET: ReadonlySet<string> = new Set(
+  KNOWN_AGENT_KINDS,
+);
+
+export const DEFAULT_AGENT_KIND: KnownAgentKind = "other";
+
+export const KNOWN_AGENT_KIND_LABELS: Record<KnownAgentKind, string> = {
+  claude_code: "Claude Code Agent",
+  codex: "Codex Agent",
+  cursor: "Cursor Agent",
+  hermes: "Hermes Agent",
+  openclaw: "OpenClaw Agent",
+  other: "Agent",
+};
+
+const MAX_AGENT_KIND_LENGTH = 64;
+
+/**
+ * Normalize a user-supplied agent kind into the canonical form Dench stores.
+ * Lower-cases, trims, replaces spaces and dashes with underscores, drops
+ * unsafe characters, caps length, and falls back to `other` when the input
+ * is missing or normalizes to empty.
+ */
+export function normalizeAgentKind(input: unknown): string {
+  if (typeof input !== "string") return DEFAULT_AGENT_KIND;
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) return DEFAULT_AGENT_KIND;
+
+  const normalized = trimmed
+    .replace(/[\s-]+/g, "_")
+    .replace(/[^a-z0-9_]/g, "")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, MAX_AGENT_KIND_LENGTH);
+
+  return normalized || DEFAULT_AGENT_KIND;
+}
+
+export function agentKindLabel(kind: string): string {
+  return KNOWN_AGENT_KIND_LABELS[kind as KnownAgentKind] ?? "Agent";
+}