Support safe agent-side API key usage without secret echo

[justrach]

Problem

When using CodeGraff from an agentic coding environment, users may paste a cg_sk_ key into chat and ask the agent to run a live SDK/API smoke test. The agent can technically call the SDK/API, but command strings and tool outputs are recorded in transcripts/logs.

Current options are awkward:

1. Put CODEGRAFF_API_KEY inline in a shell command, which records the secret.
2. Ask the user to manually export it outside the agent session, which blocks autonomous testing.
3. Decline the live test even though the key was intentionally provided for agent use.

This happened while trying to run a minimal @codegraff/sdk smoke test with model deepseek-v4. The SDK installed and imported, but the live call was blocked by secret-handling concerns.

Expected behavior

Provide an agent-friendly way to run one-off local tests without echoing the API key into commands or logs.

Potential fixes:

• CLI reads key from stdin without printing it, e.g. codegraff auth set --stdin or codegraff smoke --api-key-stdin.
• SDK/CLI supports reading a key from a file path with clear gitignore guidance.
• Document a short-lived test-token flow for coding agents.
• Provide a documented deepseek-v4 smoke command that uses env-only auth and avoids inline shell secrets.
• Add redaction guidance/helpers for agent environments where command strings are persisted.

Repro context

1. npm install @codegraff/sdk
2. Verify import works from Node and exports Graff plus Sandbox.
3. Attempt a live smoke call with a pasted cg_sk_ key and model deepseek-v4.

The blocker is safe secret handling, not SDK installation/import.

Security note

Any key pasted into chat should be treated as exposed and rotated after use. This issue is about making the intended agent-use case safer and less likely to leak secrets into transcripts/logs.

[justrach]

Follow-up: this should probably also cover the async nature of agent runs, not just secret-safe auth.

Async agent lifecycle gap

In agentic app integrations, a CodeGraff run can outlive a single HTTP request or local shell command. For example:

• Creating a sandbox may be quick.
• Installing dependencies, cloning repos, running tests/builds, or running an autonomous agent can take minutes.
• Gateway/docs already note sync exec has a Cloudflare-ish ~95s cap, so long work needs async launch + polling.
• App servers and coding agents need a stable run handle they can store and poll later.

What integrations need

A first-class documented async agent lifecycle would help:

1. Start an agent asynchronously and immediately return a stable id/handle.
2. Poll status with short calls: pending/running/completed/failed/cancelled/timed_out.
3. Fetch incremental logs/output safely, with tail/full options.
4. Fetch final structured result separately from raw transcript/logs.
5. Cancel/kill a run.
6. Stop/destroy the sandbox when terminal, with guidance on billing-safe cleanup.
7. Resume/reconnect after client disconnect or server restart using the saved handle.
8. Clearly separate sandbox exec ids vs higher-level agent run ids.
9. Provide recommended timeout/TTL/autostop defaults for app integrations.

Desired docs/API shape

Something like:

• POST /v1/agents/runs with { model, prompt, sandbox?, async: true } -> { runId, sandboxId?, state }
• GET /v1/agents/runs/:runId -> { state, exitCode?, usage?, timestamps? }
• GET /v1/agents/runs/:runId/logs?tail=N or ?full=1
• GET /v1/agents/runs/:runId/result
• DELETE /v1/agents/runs/:runId

Or, if the intended primitive remains sandbox exec, docs should show the exact recommended pattern for running an SDK agent inside a sandbox asynchronously: create sandbox -> upload/write runner -> async exec -> poll -> fetch logs/result -> destroy/stop.

This matters for products that want to launch managed agents from an API route and let users poll progress from a dashboard rather than blocking a request until completion.