crewx-agent-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrewX contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# CrewX CLI
+
+Connect an existing Codex, Claude Code, Pi, Hermes, or OpenClaw installation to a CrewX workspace. The runner stays on your machine, so the agent uses its existing login, configuration, tools, and access to the selected working directory.
+
+## One-command join
+
+Create an agent profile in CrewX, generate a token, and copy the command from its connection panel:
+
+```bash
+cd /path/to/project
+npx --yes crewx-agent-cli@latest --join <join-code>
+```
+
+Node.js 22 or newer is required. The command verifies the connection, opens an agent session, and polls for work in the foreground. Closing the terminal or pressing `Ctrl+C` disconnects it. CrewX does not install or start a background daemon automatically; use a service manager such as `launchd`, systemd, or a container supervisor if that lifecycle is wanted.
+
+Join mode does not write `$XDG_CONFIG_HOME/crewx/config.json`. Useful options include:
+
+```bash
+npx --yes crewx-agent-cli@latest --join <join-code> --cwd /path/to/project
+npx --yes crewx-agent-cli@latest --join <join-code> --once
+npx --yes crewx-agent-cli@latest --join <join-code> --adapter codex
+```
+
+The versioned join payload is base64url-encoded JSON containing the server URL, adapter, and raw `crwx_…` bearer token. Base64url is transport encoding, not encryption. CrewX shows the generated token once, but the credential inside the command is reusable until its configured expiry or revocation. Anyone who obtains the command can decode and use it, and the command may remain in shell history. Treat it as a secret and revoke the token from the agent profile if it is exposed.
+
+The server stores only the token digest. During a join-mode run, the CLI keeps the decoded credential in memory and supplies the CrewX URL and token to child agents as `CREWX_URL` and `CREWX_TOKEN` so they can use the scoped `crewx task`, `doc`, `memory`, and `integration` commands. A locally executed agent has the same trust boundary as the user account running it.
+
+## Persistent installation
+
+From this monorepo:
+
+```bash
+pnpm --filter crewx-agent-protocol build
+pnpm --filter crewx-agent-cli build
+pnpm --filter crewx-agent-cli link --global
+```
+
+After `crewx-agent-cli` is published to npm, install it globally and save a named machine connection:
+
+```bash
+npm install --global crewx-agent-cli
+crewx connect --url https://your-crewx.example --token crwx_… --name "My Mac"
+crewx doctor
+crewx daemon --adapter codex
+```
+
+The saved connection lives at `$XDG_CONFIG_HOME/crewx/config.json` (or `~/.config/crewx/config.json`) with mode `0600`. `CREWX_URL`, `CREWX_TOKEN`, and `CREWX_ADAPTER` override saved settings and are useful in explicitly secured services and CI. The CLI includes operating-system certificate authorities in Node's trust store, so locally trusted HTTPS sites such as Laravel Herd work without disabling certificate verification.
+
+Both join mode and `crewx daemon` run in the foreground. Start either command inside a safe fallback directory. For each assignment, CrewX uses the project channel's local path first, the agent profile's default working directory second, and `--cwd` last. Use `--once` for one poll and `--poll-interval 5000` to change the polling cadence.
+
+## Built-in adapters
+
+- **Codex** runs `codex exec --json … -`. CrewX maps read-only, workspace-write, and full-access profiles to the corresponding Codex sandbox and passes the prompt on stdin.
+- **Claude Code** runs `claude --print --output-format stream-json --verbose`. CrewX maps its profile to plan mode, non-interactive workspace edits, or skipped permission prompts and passes the prompt on stdin.
+- **Pi** runs `pi --mode json --no-approve`. CrewX deliberately ignores project-local Pi settings, extensions, skills, prompts, and themes on each daemon run. Read-only and chat-only profiles receive a restricted tool allowlist. Global Pi configuration still applies. Pi itself is not an operating-system sandbox.
+- **Hermes** runs `hermes acp` and speaks ACP v1 over stdio for session creation, model selection, prompt delivery, progress, permission requests, and cancellation. Workspace-write maps to Hermes `accept_edits`; full access maps to `dont_ask`. Hermes does not expose a trustworthy read-only or chat-only ACP mode, so CrewX rejects those profiles instead of presenting a false boundary. CrewX passes a configured model to Hermes for resolution.
+- **OpenClaw** runs an explicitly selected persistent agent with JSON output, a collision-resistant CrewX assignment session key, and a mode-`0600` temporary prompt file that is removed after the run. Immediately before spawning, CrewX runs `openclaw agents list --json` and `openclaw sandbox explain` for the exact task session. The configured agent workspace must resolve to the assignment directory; a sandboxed session must mount that exact directory read-write at its runtime workdir. OpenClaw owns its persistent tool policy and approval behavior, and has no per-run `--cwd`, so configure a dedicated agent with `openclaw agents add <name> --workspace "/path/to/project" --non-interactive --json` when needed.
+
+`crewx doctor` probes all five binaries. Runtime profile changes are read before every assignment, so supported model, permission, chat-only, working-directory, token, and deactivation changes do not require reconnecting. Chat-only and deactivated agents cannot receive task runs.
+
+## Custom commands
+
+Advanced users can replace the built-in invocation without editing CrewX:
+
+```bash
+npx --yes crewx-agent-cli@latest --join <join-code> \
+  --coding-cmd 'my-agent --non-interactive {prompt}'
+
+crewx daemon --adapter codex --coding-cmd 'my-agent --format text'
+crewx run codex "Review this repository" --coding-cmd 'my-agent {prompt} --quiet'
+```
+
+CrewX uses a quote-aware argv parser and launches the resulting executable with `shell: false`. The prompt replaces one exact `{prompt}` argument or is appended as one argument when the placeholder is absent; it is never interpolated into a shell string. Pipes, redirection, variable expansion, and command substitution are therefore not interpreted by CrewX.
+
+This prevents prompt text from becoming shell syntax, but it does not make an arbitrary executable safe. The selected program inherits the runner's operating-system permissions and environment, including CrewX connection variables in join mode. Do not use commands from an untrusted profile or run them in an untrusted working directory. Explicitly wrapping a command in a shell recreates the shell-risk boundary and is not recommended.
+
+## Shared work commands
+
+The same connection token lets humans and running agents maintain shared CrewX work from the terminal. JSON output is designed for local agents:
+
+```bash
+crewx task list --assigned-to-me --json
+crewx task create --title "Verify the release" --description "Run the smoke suite" --assign-to-me --json
+crewx task update 42 --status done --result "Smoke suite passed" --json
+
+crewx doc list --json
+crewx doc create --title "Release runbook" --content "# Release runbook" --json
+crewx doc update 17 --expected-version 1 --content "# Updated runbook" --summary "Add release steps" --json
+
+crewx memory list --scope channel --channel 12 --json
+crewx memory create --title "Release convention" --content "Run the browser smoke test before merging" --channel 12 --json
+crewx memory update 9 --importance 5 --json
+
+crewx integration list --json
+crewx integration search slack "release blocker" --json
+crewx integration search notion "deployment runbook" --json
+crewx integration search google_drive "quarterly plan" --json
+```
+
+Agents may update only tasks assigned to their own profile. Documents must be agent-readable and unprotected, and every document update requires the current version from `doc list`; stale updates fail instead of overwriting newer work. Agents may edit only memories they recorded, while channel-scoped memory is limited to channels they can see. Provider access tokens are encrypted by the web application and are never returned to the CLI; integration commands expose normalized search results only.
+
+## One-shot local runs
+
+The same adapters can be exercised without a CrewX connection:
+
+```bash
+crewx run codex "Summarize this repository"
+printf 'Review the current diff' | crewx run claude
+crewx run pi "Find the failing test" --cwd ./project
+crewx run hermes "Explain the architecture"
+crewx run openclaw "Check the release plan"
+```
+
+## Review reruns
+
+Tasks can require human approval. When an agent reports completion, CrewX holds the task in review. Approving completes it; requesting changes records the review note, moves it back to in-progress, and queues that note for the same agent as its next iteration. Existing task and pull-request context stays attached. A new GitHub push also resets a prior approval and returns the task to review.
+
+Run `crewx --help` or `crewx <command> --help` for every option.
+
+## CrewX agent API
+
+The CLI targets `/api/agent/v1`, including connection lifecycle plus `/tasks`, `/documents`, `/memories`, and `/integrations`, authenticated with the bearer connection token. Protocol lifecycle payloads are runtime-validated by `crewx-agent-protocol`.
+
+CrewX's implementation choices were informed by a clean-room static inspection of the public `hilos-agent` package. CrewX is an independent implementation and does not include Hilos source code.

package/dist/adapters.d.ts

@@ -0,0 +1,67 @@
+import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'node:child_process';
+import { type AgentAdapter } from 'crewx-agent-protocol';
+export interface AdapterInvocation {
+    command: string;
+    args: string[];
+    output: 'jsonl' | 'json' | 'text';
+    prompt: {
+        type: 'stdin';
+    } | {
+        type: 'argument';
+        index: number;
+    } | {
+        type: 'file';
+        flag: string;
+    };
+}
+export interface AgentRuntimeProfile {
+    model?: string;
+    permissionPreset?: 'read_only' | 'standard' | 'full_access';
+    chatOnly?: boolean;
+    sessionKey?: string;
+    runtimeAgentId?: string;
+}
+export interface ParsedAdapterLine {
+    raw: unknown;
+    message?: string;
+    role?: 'assistant' | 'tool';
+    eventType?: string;
+}
+export interface AdapterRunResult {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    messages: string[];
+    stdout: string[];
+    stderr: string[];
+}
+export type SpawnProcess = (command: string, args: readonly string[], options: SpawnOptionsWithoutStdio) => ChildProcessWithoutNullStreams;
+export declare function parseAdapter(value: string): AgentAdapter;
+/** Adapter commands are represented as argv and are never evaluated by a shell. */
+export declare function buildAdapterInvocation(adapter: AgentAdapter, profile?: AgentRuntimeProfile, codingCommand?: string): AdapterInvocation;
+export declare function parseCodingCommand(value: string): string[];
+export declare function parseAdapterLine(adapter: AgentAdapter, line: string): ParsedAdapterLine;
+export declare function verifyOpenClawRuntime(options: Pick<RunAdapterOptions, 'cwd' | 'environment' | 'spawnProcess'> & {
+    profile: AgentRuntimeProfile;
+}): Promise<void>;
+export interface RunAdapterOptions {
+    adapter: AgentAdapter;
+    prompt: string;
+    cwd: string;
+    profile?: AgentRuntimeProfile | undefined;
+    codingCommand?: string | undefined;
+    environment?: NodeJS.ProcessEnv | undefined;
+    timeoutMs?: number | undefined;
+    maxOutputBytes?: number | undefined;
+    signal?: AbortSignal | undefined;
+    spawnProcess?: SpawnProcess | undefined;
+    onStdout?: ((line: string, parsed: ParsedAdapterLine) => void) | undefined;
+    onMessage?: ((message: string, role: 'assistant' | 'tool') => void) | undefined;
+    onStderr?: ((line: string) => void) | undefined;
+}
+export declare function runAdapter(options: RunAdapterOptions): Promise<AdapterRunResult>;
+export declare function probeAdapter(adapter: AgentAdapter, spawnProcess?: SpawnProcess, timeoutMs?: number): Promise<{
+    available: boolean;
+    version?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,8BAA8B,EAAE,KAAK,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAM/G,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAK7E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,MAAM,EACF;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GACjB;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACnC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,wBAAwB,KAC9B,8BAA8B,CAAC;AAuEpC,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAMxD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,mBAAwB,EACjC,aAAa,CAAC,EAAE,MAAM,GACrB,iBAAiB,CA+FnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA6C1D;AAwDD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAoDvF;AA2FD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,aAAa,GAAG,cAAc,CAAC,GAAG;IACzE,OAAO,EAAE,mBAAmB,CAAC;CAC9B,GACA,OAAO,CAAC,IAAI,CAAC,CAwEf;AAmCD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC1C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC3E,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAChF,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACjD;AA0cD,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBtF;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,YAAY,GAAE,YAAoC,EAClD,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkGnE"}