@margay/ccl-core 1.4.5-rc.9 → 1.4.6-beta.0

package/sdk/README.md

@@ -66,6 +66,43 @@ process events. Those events do not replace or add a terminal result.
 See the [API contract](./API.md) and [recovery guide](../docs/error-recovery-usage.md)
 for consent, external blockers, and continuation rules.
 
+## Gateway request status (source candidate)
+
+Set `includeRequestProgress: true` to receive nonterminal `request_progress`
+events. This is off by default, independent of raw/partial/error diagnostic
+options. It does not change `result`, cancellation, or `onSessionEnd`.
+
+```ts
+for await (const event of query('Summarize this project.', {
+  includeRequestProgress: true,
+})) {
+  if (event.type === 'request_progress') {
+    const { requestId, phase, attempt, elapsedMs, idleMs, slow } = event.progress
+    // Update a transient status indicator, keyed by requestId.
+  }
+  if (event.type === 'result') {
+    // End the turn using the existing success/error contract.
+  }
+}
+```
+
+Phases are `preparing`, `connecting`, `sending`, `waiting_response`,
+`response_headers`, `retry_wait`, `streaming`, and `finished`. `connecting`
+includes pool waiting, DNS, TCP, TLS and proxy negotiation; it does not identify
+which of those substeps is slow. `idleMs` measures time without effective model
+progress. Events contain no prompt, headers, credentials or endpoint URL.
+
+Events are finite (at most 32 per model request), not periodic heartbeats.
+A slow notice never counts as model progress or grants permission to retry.
+`finished` ends a request, not necessarily the turn; clear status on the existing
+result/abort/disconnect path as well. Hosts should keep their own deadlines
+and avoid replaying tools when the remote completion state is unknown.
+
+CLI users can opt in with `--print --output-format stream-json
+--include-request-progress`; each wire event is `system/request_progress`.
+The flag is invalid with text or JSON output. See
+[request deadlines](../docs/gateway-quickstart.md#request-deadlines-and-slow-waits).
+
 ## Architecture
 
 The SDK is the **host side** of the stream-json control protocol that
@@ -146,3 +183,60 @@ provider mapping, skills-dir wrapping, hooks, usage accumulation, file-store
 round-trip. The issue's live end-to-end DoD slice (real model + mock outbound
 endpoint + real process exit) is CoS-side per the issue's division of labor —
 the SDK-side seams it needs are all covered above.
+# Minimal mode and explicit tools
+
+When passing `--bare` through `extraArgs`, the built-in tool set is Bash, Read,
+and Edit (REPL/coordinator modes have their own subset). `--tools default` uses
+that mode's available set; an explicit incompatible selection such as
+`--bare --tools Write` fails with a diagnostic before a model request. Remove
+`--bare` and unset `CLAUDE_CODE_SIMPLE` to request Write. Allow/deny permissions
+still apply; `--allowedTools` does not add tools to the available set.
+
+Use `extraArgs: ['--thinking', 'disabled']` to explicitly disable thinking on
+Anthropic Messages compatible routes. Omitting the option retains the route's
+default. The selection persists across requests; a query handle's
+`setMaxThinkingTokens(0)` explicitly disables it, and `null` restores the default.
+# Persistent sessions and streamed input
+
+`query({ prompt: asyncIterable, options })` accepts `SDKUserMessage` values. It
+submits one message at a time, waits for its result before pulling the next,
+and adds the input UUID as `result.turnId` (generating a UUID if omitted).
+Input EOF closes a streamed query. Invalid messages or producer failures reject
+the event iterator. Consume events as they arrive: an unread streamed query fails
+explicitly at 1024 buffered events instead of retaining unlimited output.
+
+Use `createSession` when the host owns a longer conversation:
+
+```ts
+import { createSession } from '@margay/ccl-core/sdk'
+
+const session = createSession({ cwd: projectDir, maxPendingTurns: 32 })
+try {
+  const first = session.prompt('Inspect the project and describe the failing test.')
+  console.log(await first.result)
+  const next = session.followUp('Fix that failure and run the relevant test.')
+  console.log(await next.result)
+  await session.endInput()
+  // The same child and controls remain alive until close().
+  console.log(session.pid, await session.controls.initializationResult())
+} finally {
+  await session.close()
+}
+```
+
+`prompt` and `followUp` enqueue FIFO; exceeding `maxPendingTurns` throws before
+acceptance. Each `Turn` has a stable `id`, a `result` promise and `cancel()`.
+Cancelling a queued turn rejects its promise. Cancelling an active turn interrupts
+the CLI and returns its interrupted result; already executed tool effects remain.
+`steer(text)` interrupts the active turn and puts the correction ahead of waiting
+follow-ups. It does not undo earlier effects. `endInput()` rejects new inputs and
+waits for accepted turns while preserving controls; `close()` terminates the child
+and rejects unfinished turns. `onEvent` observes events without retaining history.
+
+Permission callbacks can wait for a host decision while the process stays alive.
+Interrupt and close cancel that wait. Returning `{ behavior: 'pending' }` retains
+the existing durable suspend contract: it ends this process and requires
+`resumeWithDecision(sessionId, decision)`; it does not imply automatic approval.
+Uncooperative application iterators/callbacks cannot be forcibly stopped, but do
+not prevent CLI cleanup. One-shot string queries and post-result `rewindFiles`
+retain their existing behavior.