dingtalk-workspace-cli/docs/event-subprocess-contract.md

Event consume — AI subprocess contract

Defines the stable dws event consume subprocess contract so an orchestrator can determine when the consumer is ready, stop it cleanly, and machine-read why it exited.

Scope of this branch: the six contract items below. Reconnect resilience (keeping the stream alive across a transient upstream drop) is tracked separately and intentionally out of scope here.

Baseline (already present, no work)

• --max-events N — stop after N events (exit 0).
• --duration D — wall-clock budget (exit 0). Kept as --duration, NOT aliased to --timeout: the global --timeout is the HTTP request timeout (int seconds) and would collide (different type and meaning).
• Bus idle-shutdown fires only with zero consumers, so a connected consumer is never idle-killed.
• SIGINT/SIGTERM already cancel the run context and return cleanly.

Improvements

1. Ready marker (standardized)

On connect, emit a fixed stderr line before any stdout event:

[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>

Parents block on stderr until this line, then read stdout. Suppressed under --quiet. Replaces the ad-hoc connected bus pid=... line (which omits event_key).

Verification

• T1a: stderr contains a line matching ^\[event\] ready event_key=<key>.
• T1b: that line appears before the first stdout event (ordering).
• T1c: with --quiet, the line is absent.

2. stdin EOF = graceful exit

consume watches stdin; closing stdin is a shutdown signal (wired for AI subprocess callers). To stay resident, feed a never-EOF stdin (< <(tail -f /dev/null)) or run bounded (--max-events / --duration).

Verification

• T2a: printf '' | dws event consume <key> exits ≤2s, code 0, final line reason: signal (stdin-eof classified as signal).
• T2b: dws event consume <key> < <(tail -f /dev/null) still alive after 5s, connection intact.
• T2c (unit): a controllable stdin reader hitting EOF makes Run return nil via the cleanup path.

3. Exit reason contract + exit codes

On exit, final stderr line:

[event] exited — received N event(s) in Xs (reason: <limit|timeout|signal|bus_shutdown>)

Exit codes: controlled exit (limit/timeout/signal/stdin-eof) = 0; startup or runtime failure (permissions, network, params) = non-zero, with no exited line and an Error: line instead.

Verification

• T3a: --max-events 1 + 1 event → exit 0, reason=limit, N=1.
• T3b: --duration 2s, no events → exit 0, reason=timeout.
• T3c: SIGTERM mid-run → exit 0, reason=signal.
• T3d: bad params / permission failure → exit≠0, no exited line, has Error:.
• Unit tests assert (reason string, exit code) for each path.

4. Cleanup on exit (no kill -9)

Ownership-based cleanup:

• If this run created the subscription (no --subscribe-id), a clean exit (SIGTERM / SIGINT / stdin-EOF / limit / timeout) unsubscribes it server-side and sends Bye.
• If --subscribe-id was passed (reusing an existing subscription), the subscription is left intact — the caller owns its lifecycle.
• --ephemeral remains as an explicit "always unsubscribe" override.
• Help/docs warn: avoid kill -9 (skips the unsubscribe → leaked server-side subscription: "subscription already exists" on restart, duplicate delivery). Prefer SIGTERM or closing stdin.

Verification

• T4a: start consume (self-created subscription), record subscribe_id; SIGTERM; afterwards dws event status no longer lists that subscribe_id and the server-side subscription is gone.
• T4b: start consume with --subscribe-id <existing>; SIGTERM; the subscription is still present (reuse case preserved).
• T4c (control): kill -9 leaves subscribe_id lingering (documented risk; we only guarantee SIGTERM is clean, we do not fix kill -9 itself).

5. Subscription-create retry orchestration and local guard

This policy covers all 16 public personal-event keys and every logical subscription in a multi-event command. It applies only before the ready marker; reconnecting an established Stream remains a separate mechanism.

• The 0/2/1 limits below are an Agent/host orchestration contract, not a CLI-enforced persisted total-attempt cap. Each dws event consume process sends at most one subscription-create HTTP request for a logical subscription and performs no in-process automatic retry. The CLI persists only the in_flight, cooldown, and terminal_hold guard states; it does not persist or enforce the Agent/host attempt count across invocations.
• ID resolution, event consume, and later event status/stop must use the same --profile. A user or conversation ID resolved under another profile must not be reused for the current subscription.
• A logical subscription is keyed by the current profile/identity, event key, rule type, target, and filters. A new subscribe_id, trace_id, or process does not create a new logical operation or reset the Agent/host budget.
• For the Agent/host, retryable=false means max_additional_attempts=0.
• For the Agent/host, retryable=true means max_additional_attempts=2. It must honor retry_after_seconds or next_retry_at when present and must not retry early.
• For the Agent/host, an omitted retryable value (retryable=unknown) means max_additional_attempts=1; a second unknown failure stops the operation.
• in_flight means the original logical request is still running. cooldown and terminal_hold mean a guard is already delaying or blocking it. These states must not recursively launch event consume, start a parallel equivalent subscription, or bypass the guard with a new subId or trace. The caller waits for the original request/guard or stops, while the Agent/host keeps its own orchestration count.
• A multi-event command remains one original operation. A caller must not split out a failed event, reorder events, or restart the command to bypass a budget. Existing startup rollback cleans subscriptions created before a later item fails.

Local guard state operations

• The default open-edition state file is ~/.dws/events/open/personal_stream/<identity_hash>/personal_subscription_attempts.json. The config root follows DWS_CONFIG_DIR when set, and another edition uses that edition's directory instead of open.
• The identity directory is mode 0700; both personal_subscription_attempts.json and personal_subscription_attempts.lock are mode 0600.
• A failure streak resets after 24h without another failure. A terminal_hold lasts 1h. Prefer waiting until the reported next_retry_at; do not clear the file as a normal retry mechanism.
• For emergency recovery, first ensure that no subscription-create process is running for that identity. Delete only personal_subscription_attempts.json, never the lock file. This clears every protection record for that identity, not just one event.

Verification

• T5a (policy): skill/docs tests pin the Agent/host 0/2/1 orchestration contract and explicitly reject describing it as a CLI-persisted hard cap.
• T5b (CLI): one process issues at most one create request per logical subscription; a changed subId/trace or process restart does not bypass the persisted fingerprint guard.
• T5c: in_flight/cooldown does not recursively issue another create.
• T5d: multi-event startup cannot be split or reordered to bypass the guard, and a partial startup still rolls back earlier subscriptions.
• T5e: state-store tests cover 0700/0600 permissions, 24h reset, 1h terminal_hold, and identity-scoped cleanup; skill/docs tests pin the operational recovery instructions.

6. Host runtime-token handoff

When the root command carries an explicit host-supplied --token, personal event control requests and the foreground Stream use that token with higher priority than local OAuth. A detached bus receives it only through the owner-only local IPC transport:

1. The child starts in runtime-token mode with non-sensitive identity and ticket metadata only; neither its argv nor environment contains the token.
2. The consumer sends Hello with credential_mode=runtime_token.
3. The bus advertises the additive runtime_token_v1 capability and its in-memory credential generation in HelloAck.
4. Only after that capability is confirmed does the consumer send a bounded credential_update frame. The bus applies it with generation CAS, replies with credential_update_ack, and registers the consumer only on success.

The bus blocks ticket acquisition until the first runtime credential arrives. A later invocation may rotate Token A to Token B on a compatible existing bus; the current WebSocket remains connected and the next ticket request or natural reconnect uses B. If a 401 rejects the current runtime token, only an already installed newer generation is retried; the runtime path never refreshes or falls back to a local OAuth profile and never suggests dws auth login.

Clients do not send a token to a bus that lacks the capability, do not stop other consumers automatically, and fail before printing the ready marker. With no explicit --token, the original OAuth, refresh, profile, and old-client to new-bus protocol behavior remains unchanged.

Verification

• T6a: a stale local Token A and root Token B produce control and ticket requests authenticated only with B.
• T6b: compatible bus reuse supports A-to-B rotation and generation conflicts; 401 retries only an already-installed newer runtime token.
• T6c: an old bus receives no credential and remains running; the new consumer exits before its ready marker.
• T6d: a canary credential is absent from child argv/environment, dry-run, stdout/stderr, bus.meta, bus.log, run state, and returned errors.
• T6e: no-token OAuth, refresh, multi-profile, marker/cache, and bus-reuse tests continue to pass.

Out of scope (next branch)

Reconnect resilience — today personal source retries only retryable errors (1–30s backoff); a non-retryable error tears the bus down and takes consume with it (the likely cause of the observed silent drop). Making more drops retryable, keeping the bus alive across a reconnect, and emitting reason: source_lost only after exhausting the budget — tracked on its own branch, since it needs error-classification judgement and real flaky-network testing, and would otherwise couple clean contract work with resilience work.

Test surface

• Unit: extend internal/event/consume/*_test.go with fake bus conn / stdin / stderr sink for T1c, T2c, T3 (all paths), T4 ownership branch.
• Integration/e2e: --foreground + mock source (or a short real run) for T1a/b, T2a/b, T3a–d, T4a/b/c — assert the stderr contract lines and exit codes.