ak run

Resolve local Kit skill và stream qua Claude Code, Codex, Cursor, DeepSeek Harness, Grok Build hoặc Oh My Pi với hành vi stdin, timeout, output và dependency rõ ràng.

Dùng ak run để chạy một skill qua coding-agent adapter cục bộ. Lệnh resolve skill từ Kit source, activate managed runtime đã khai báo nếu có, dựng prompt từ skill instruction và argument của bạn, rồi start backend CLI đã chọn.

Cách dùng

ak run <kit>/<skill> [args...] [flags]

Reference phải có đúng một slash và dùng dạng lowercase canonical. Tên bundled skill không prefix có thể resolve export ak-, vì vậy engineer/scout có thể chọn skill export ak-scout.

Tuỳ chọn

Cờ	Mặc định	Mô tả
`--target <adapter>`	`claude-code`	Chọn `claude-code`, `codex`, `cursor`, `dsh`, `grok` hoặc `omp`.
`--kits-dir <dir>`	`AGENTKIT_KITS_DIR` hoặc `./kits`	Chọn thư mục Kit source cục bộ.
`--timeout <duration>`	`0s`	Đặt deadline cho invocation; zero tắt command timeout.

Cờ dùng chung nằm trong quy ước CLI. Không có preview, apply, force hay confirmation chung.

Route một invocation qua adapter DeepSeek Harness hoặc Grok đã đăng ký, hoặc qua harness dispatch target Oh My Pi. Projection Kit Pi không phải adapter ak run trong bản phát hành này; dùng ak kit init ... --target pi cho Skill cài vào Pi và dùng discovery riêng của Pi để gọi chúng.

ak run engineer/scout --target grok
ak run engineer/scout --target dsh
ak run engineer/scout --target omp

Backend và credential

Target	Backend invocation	Gate trước dispatch
`claude-code`	`AGENTKIT_CLAUDE_BIN` hoặc `claude` trên `PATH`; prompt qua stdin.	Cần Anthropic/OpenAI key trong environment hoặc AgentKit config, trừ khi `AK_DISABLE_FIRSTRUN_GATE=1`.
`codex`	`AGENTKIT_CODEX_BIN` hoặc `codex` trên `PATH`; chạy `codex exec -`.	Bỏ provider gate; Codex quản lý auth.
`cursor`	`AGENTKIT_CURSOR_BIN` hoặc `agent` trên `PATH`; dùng non-interactive `stream-json`.	Bỏ provider gate; Cursor quản lý auth.
`dsh`	`AGENTKIT_DSH_BIN` hoặc `dsh` trên `PATH`.	DeepSeek Harness quản lý model, credential và quyền thực thi.
`grok`	`AGENTKIT_GROK_BIN` hoặc `grok` trên `PATH`; dùng `--prompt-file <temporary-file> --output-format streaming-json`.	Bỏ provider gate; Grok quản lý auth, model, trust, permission, sandbox và `config.toml`.
`omp`	`AGENTKIT_OMP_BIN` hoặc `omp` trên `PATH`; chạy `omp -p --mode json --no-session --cwd <cwd> @<prompt-file>`.	Bỏ provider gate; Oh My Pi sở hữu backend và credential đã cấu hình.

ak run --target grok dispatch qua adapter Grok native và để Grok sở hữu authentication, model, trust, permission cùng sandbox. ak run --target omp là harness dispatch cục bộ qua Oh My Pi. Tuyến này tách biệt với các projection Kit có thể cài, gồm ak kit init <kit> --target pi và ak kit init <kit> --target omp, và không thay thế bản cài Kit ở project hoặc global.

DeepSeek Harness chạy dispatch headless one-shot. AgentKit truyền prompt đã tạo qua process argument, vì vậy không đưa secret vào yêu cầu Skill hoặc argument.

Với Claude Code, thiếu provider key trong JSON, quiet, noninteractive hoặc CI=1 sẽ ghi warning và thoát 4. Ở mode mặc định, lệnh đọc stdin và hỏi Run 'ak setup' now? [Y/n]:. Trả lời yes không mở setup trong path này; lệnh vẫn thoát 4. Trả lời no hoặc EOF thoát 3. Gate không kiểm tra stdin có phải TTY hay không.

Parent stdin không được forward đến backend sau launch. Prompt hoàn chỉnh được ghi rồi child stdin đóng. Đừng dùng ak run cho backend workflow cần input tương tác tiếp theo.

Prompt và riêng tư

AgentKit đọc SKILL.md đã resolve, normalize, bỏ một số invisible character, wrap thành Kit content không tin cậy kèm digest, rồi nối mọi CLI argument còn lại bằng khoảng trắng. Prompt đó được gửi đến backend và có thể truyền tới provider.

Lệnh không redaction secret trong skill text, argument, backend output hay error. Tránh truyền credential làm argument. JSON mode escape child bytes thành event string; escaping không phải redaction.

Với OMP, AgentKit ghi prompt đã tạo vào file tạm mode 0600, chỉ truyền tham chiếu @<path> của file cho process rồi xóa file khi process kết thúc. Cơ chế này giữ nội dung prompt khỏi danh sách argument của process; nó không thay đổi ranh giới truyền tới provider hoặc redaction ở trên.

Khi skill khai báo Python hoặc Node runtime, AgentKit activate managed environment hiện có. Environment thiếu thoát 4 với gợi ý ak skill install; environment corrupt thoát 4 với gợi ý ak skill repair. Chỉ đặt AGENTKIT_SKILL_RUNTIME=0 khi cố ý opt out managed runtime.

Required adapter capability không có fallback cũng thoát 4. Gap optional hoặc có fallback là warning trên stderr trừ khi dùng --quiet.

Luồng và JSON protocol

Trong human mode, backend stdout đi stdout và backend stderr đi stderr. Status start/end của AgentKit cũng đi stderr trừ khi --quiet.

--json ghi schema-v1 NDJSON event ra stdout, không phải một JSON envelope. Event type gồm start, env_activate, chunk, error và end. Activation event báo ok hoặc skipped trước backend chunk. chunk.stream là stdout hoặc stderr. Terminal event non-zero có exit_code; interrupt và timeout thêm boolean. Vì field zero bị omit, end success không có exit_code.

Failure trước streaming dùng shared structured error trên stderr thay vì NDJSON sequence. Backend thiếu sau start tạo event NDJSON error và end trên stdout. Hãy consume stdout theo từng dòng và kiểm tra process status riêng.

Timeout, cancellation và process

--timeout chỉ áp dụng cho backend invocation. Deadline dương cancel adapter process và thoát 1; zero nghĩa là không giới hạn. SIGINT/SIGTERM cancel process group nơi được hỗ trợ và thoát 3. Backend nhận graceful termination trước, sau đó forced termination sau một grace period ngắn.

Adapter có thể truy cập network, provider credential, working directory và process environment kế thừa. Managed runtime variable được thêm vào child; adapter Codex và Cursor bỏ managed loader override LD_* và DYLD_* trước launch.

Hiệu ứng disk và activity record

ak run đọc tệp Kit/skill. Backend có thể ghi working file, session data, cache hoặc thay project. Riêng AgentKit best-effort append event run.started và run.completed hoặc run.failed vào:

~/.agentkit/activity/events.ndjson

AGENTKIT_HOME đổi path. Activity chứa skill reference, adapter, timestamp, duration và exit code, không chứa prompt hay backend output. Logging failure bị bỏ qua và không làm run fail. Event append-only không có backup/rollback.

Mã thoát

Mã	Ý nghĩa
`0`	Backend hoàn tất thành công.
`1`	Runtime, stream, timeout, prompt-build hoặc adapter thất bại.
`2`	Reference, target, argument hoặc cờ không hợp lệ.
`3`	Provider-key prompt bị từ chối/kết thúc hoặc invocation bị interrupt.
`4`	Thiếu provider key, managed skill environment, required capability hoặc backend binary.
`5`	Không tìm thấy Kit hoặc skill trong source đã chọn.

Backend process đã start và thoát bằng positive non-zero status khác sẽ được propagate thành process exit đó. Đừng giả định mọi backend failure trở thành 1.