Copilot

client.copilot exposes Core's ten authenticated copilot routes. The model is configured by the operator; SDK requests contain no provider credentials. A run executes registered reads, parks questions and proposed writes, and stores its state and result handles. The protocol does not establish answer quality.

from kamiwaza_sdk.schemas.copilot import RunCreate, ThreadCreate

thread = client.copilot.create_thread(ThreadCreate(title="Inspect this platform"))
run = client.copilot.create_run(RunCreate(thread_id=thread.id, query="Inspect readiness"))
print(run.id, run.status)

Use get_run, list_threads, and list_thread_runs to read retained state. A foreign thread currently lists no runs; get_run and get_result refuse foreign IDs. Lists are snapshots with no pagination. list_actions includes non-executable descriptors: check executable and let Core enforce capability. Even discovery requires a configured model.

For a waiting_for_user run, pass a QuestionAnswer(value="...") to answer_question. Inspect the next state; answering a question is not consent to a write. For pending_write, display its action, effect, and arguments to the user. Only after explicit approval, call:

from kamiwaza_sdk.schemas.copilot import WriteConfirmation

proposal = run.pending_write
# Approval happens in the calling application before this statement.
run = client.copilot.confirm_write(
    run.id,
    WriteConfirmation(confirmed=True, confirmation_token=proposal.confirmation_token),
)

The token is a SecretStr: ordinary repr and JSON dumps redact it. The SDK unseals it only into the confirmation request. Do not print it, enable HTTP tracing, or log request bodies. Run-returning methods (including cancellation) and confirmation are explicitly withheld from agent tools because they may return this credential; thread creation requires agent approval.

Core reports budgets; the SDK preserves future states, limits, errors and response fields. Each method makes one logical client call: it does not add a polling, approval or resumption loop. The shared HTTP client's authentication and transport policies still apply. A transport timeout does not imply that Core canceled or rolled back work. cancel_run stops a nonterminal run, but cannot undo an action already executed. Core has no copilot thread/run delete route; canceling and deleting a test account do not assert erasure of history.

The integration replay is selected by pytest -m integration and requires KAMIWAZA_TEST_COPILOT_PROTOCOL=1, disposable identities, and an operator configured scripted model served by tests.integration.copilot_protocol_fixture. It does not substitute a scripted result for a claim about model reasoning.