ruhken-agent-runtime 0.0.1__tar.gz

ruhken_agent_runtime-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*.*.*"
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check
+      - run: mypy src
+      - run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push'
+    outputs:
+      is_tag: ${{ steps.version.outputs.is_tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Compute version
+        id: version
+        run: |
+          pip install setuptools-scm
+          VERSION=$(python -m setuptools_scm)
+          echo "Computed version: $VERSION"
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            if [[ "$VERSION" == *".dev"* ]]; then
+              echo "ERROR: dev version on tag build" >&2
+              exit 1
+            fi
+            echo "is_tag=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_tag=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_RUHKEN_AGENT_RUNTIME=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Build
+        run: pip install build && python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: build
+    if: needs.build.outputs.is_tag == 'false'
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    if: needs.build.outputs.is_tag == 'true'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ruhken_agent_runtime-0.0.1/.gitignore

@@ -0,0 +1,67 @@
+live-smoke-artifacts/*
+
+.idea/
+.claude/
+*.pyc
+.tmp*.md
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Mypy / Ruff / other caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+cython_debug/
+

ruhken_agent_runtime-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11.3

ruhken_agent_runtime-0.0.1/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md instructions for D:\Bootcamp\Projects\agent_runtime
+
+<INSTRUCTIONS>
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues (`Johannes-Kutsch/agent_runtime`). See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context repo - `CONTEXT.md` at the root plus `docs/adr/`. See `docs/agents/domain.md`.
+
+</INSTRUCTIONS>
+

ruhken_agent_runtime-0.0.1/CLAUDE.md

@@ -0,0 +1,15 @@
+# CLAUDE.md instructions for D:\Bootcamp\Projects\agent_runtime
+
+<INSTRUCTIONS>
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues (`Johannes-Kutsch/agent_runtime`). See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context repo - `CONTEXT.md` at the root plus `docs/adr/`. See `docs/agents/domain.md`.
+
+</INSTRUCTIONS>
+

ruhken_agent_runtime-0.0.1/CONTEXT.md

@@ -0,0 +1,113 @@
+# agent_runtime Context
+
+## Purpose
+
+`agent_runtime` is the reusable runtime boundary for agent execution. It owns contracts consumed by application adapters without importing the application.
+
+## Ubiquitous Language
+
+| Term | Meaning |
+| --- | --- |
+| `agent_runtime` | Reusable runtime package and stable core public surface. |
+| `Runtime Public Surface` | Documented stability surface: runtime consumer entrypoints, runtime value objects, and built-in provider selection, not every importable symbol. |
+| `Runtime Consumer Surface` | Ordinary consuming-project entrypoints for executing prepared agent work without implementing runtime or provider adapters. |
+| `Built-in Provider Invocation` | Internal runtime mechanism behind `RuntimeClient` that executes one prepared built-in provider command and returns observable invocation facts. |
+| `ProviderAuth` | Immutable credential data carried by `ProviderSelection` for new provider selection, or supplied to Resume Session Run because continuations must not store credentials. |
+| `ProviderSelection` | Public request value selecting one service, model, effort, and provider credentials for one runtime invocation. |
+| `Consumer Fallback` | Consuming-project orchestration that chooses whether to start a separate runtime invocation after a prior invocation completes or fails. |
+| `ToolPolicy` | Closed public value describing allowed provider tools: `NONE`, `INSPECT_ONLY`, `NO_FILE_MUTATION`, or `UNRESTRICTED`. |
+| `Invocation Directory` | Host directory where runtime launches a provider command; public request field is `invocation_dir`. |
+| `Tool Workspace` | Invocation Directory when runtime exposes it through provider tools. |
+| `Ephemeral Run` | Runtime invocation that does not prepare or promise provider-session continuity. |
+| `Start Session Run` | Runtime invocation that selects a service and prepares provider-session continuity. |
+| `Resume Session Run` | Runtime invocation that continues an existing provider-session continuity chain without fallback or reselection. |
+| `Session-backed Provider` | Built-in provider that can produce and consume portable continuation data. |
+| `Continuation` | Opaque portable resume token callers persist and pass back to resume a continuity chain. |
+| `InvocationRecord` | Structured runtime output describing an invocation for caller persistence or display. |
+| `Live Runtime Output` | Provider-neutral observable agent-message text and selected service identity emitted during runtime invocation. |
+| `RuntimeClient` | Caller-owned runtime object that executes runtime requests without durable provider session storage or cross-call provider availability policy. |
+| `RuntimeOutcome` | Canonical result category for one runtime invocation: completion, usage limits, cancellation, timeout, selected-provider temporary unavailability, or retryable provider failure. |
+| `Live Provider Smoke Test` | Opt-in validation run outside default tests that exercises real built-in providers through Runtime Public Surface. |
+| `Full Live Smoke Matrix` | Maintainer confidence scope for Live Provider Smoke Tests: all lifecycle modes plus every public `ToolPolicy` for each selected configured provider. |
+| `Live Smoke Default` | Cost-first runtime-supported provider/model/effort tuple used by Live Provider Smoke Tests when callers provide no CLI or environment override. |
+| `ProviderUsage` | Provider-reported usage metadata: input/output tokens, cache-read/cache-creation input tokens, optional USD cost, and optional provider duration. |
+
+## Boundary Rules
+
+- Runtime package must remain importable without application modules.
+- Application prompt rendering, CLI wiring, issue orchestration, output parsing, display, redaction, durable trace persistence, and retention belong outside runtime boundary.
+- Runtime Public Surface is documented stability promise, not inventory of importable symbols.
+- Runtime Consumer Surface uses `RuntimeClient`, lifecycle requests, public outcome/result values, `ProviderSelection`, `ProviderAuth`, `Continuation`, `InvocationRecord`, and `ToolPolicy`.
+- Consumers import ToolPolicy from public runtime/root modules, not from adapter contract modules.
+- Ordinary consumers select built-in providers through runtime call arguments, not provider services, service registries, execution adapters, provider-session adapters, command builders, provider event parsers, or provider DTO streams.
+- Consumer-defined provider services are not supported runtime functionality.
+- Prompt-runtime execution adapter paths are retired.
+- `RuntimeClient` owns no cross-call provider availability policy, durable provider state, or logs.
+- Provider selection remains caller-supplied through the `provider_selection` request field; runtime validates built-in service, model, effort, and relevant credentials.
+- ProviderSelection construction validates value shape; invocation validates built-in provider support and availability.
+- ProviderSelection requires explicit service, model, and effort; selection defaults belong to consumers or maintainer tooling.
+- `ProviderSelection.auth` is optional; selected providers that require explicit credentials validate the relevant ProviderAuth field during invocation.
+- ProviderSelection equality includes credentials, but textual representations must not reveal credential values.
+- ProviderAuth equality includes credential values, but textual representations must redact them.
+- Resume Session Run derives provider identity from the continuation and accepts request-time ProviderAuth only for credentials.
+- Runtime does not perform provider fallback inside a single invocation; fallback is Consumer Fallback across separate invocations.
+- Runtime outcomes and exceptions describe one invocation only and do not classify Consumer Fallback eligibility.
+- `no_service_available` describes temporary unavailability of the selected provider before model work starts, not exhaustion of a provider chain.
+- Unsupported service, model, or effort selections are configuration errors, not `no_service_available` outcomes.
+- Normal RuntimeOutcome values identify the selected provider service, model, and effort for the invocation.
+- Runtime results report selected provider facts for one invocation, not Consumer Fallback attempt paths.
+- Invocation records describe one runtime invocation and do not carry Consumer Fallback group or attempt identifiers.
+- Built-in provider credentials are part of `ProviderSelection`; missing explicit credentials are credential failures and do not trigger Consumer Fallback inside runtime.
+- Runtime-owned selection, availability, resumability, failure classification, path-safety validation, and provider parsing stay inside runtime boundary.
+- Built-in Provider Invocation is internal and must not become a consumer-defined adapter extension point or request-time injection point.
+- WorkInvocation and execution adapter seams are internal and must not be consumer-accessible.
+- Public-looking internal modules should be moved behind underscore-prefixed module names before release where practical.
+- Retiring a concept means deleting obsolete code where feasible; any internal survival requires a current built-in runtime purpose and must not reappear on documented/root/runtime surfaces.
+- Built-in Provider Invocation must use runtime-neutral internal artifact names, not pycastle-specific prompt or session naming.
+- Provider event DTOs, provider-specific session details, command rendering, stream parsing, and provider flag profiles are internal.
+- Public provider failure diagnostics may expose provider observations; consumers own storage, display, and redaction.
+- Live Runtime Output is per-request observation of `AgentMessageTurn` values, not arbitrary provider chunks, token streaming, replay, logs, or alternate lifecycle entrypoints.
+- Live Runtime Output is independent of session lifecycle and `ToolPolicy`; completed runtime output remains authoritative.
+- Live Runtime Output observers are synchronous, notification-only, at-most-once per provider attempt, and consumer-owned for async bridging and backpressure.
+- Live Runtime Output callback failures propagate as exceptional consumer failures.
+- Session continuity and tool policy are independent runtime concerns.
+- Ephemeral execution does not intentionally prepare provider-session continuity.
+- Start Session Run returns continuation state; callers own persistence and retention.
+- Resume Session Run continues an existing continuity chain without Consumer Fallback or reselection.
+- Continuations are opaque, portable, semantically immutable, and may carry provider-owned serializable resume state.
+- Continuations and invocation records must not intentionally persist ProviderAuth values.
+- Runtime does not guarantee redaction of arbitrary prompt text, provider output, or diagnostics; consumers own durable redaction policy.
+- Continuations may carry provider identity and resume state, but not ProviderSelection objects.
+- Session-backed execution is limited to built-in providers that produce and consume portable continuation data.
+- Runtime must not own durable provider-session storage, durable invocation-log storage, or cleanup policy.
+- Resumed-session availability or usage-limit failures do not invalidate continuations and must not trigger automatic Consumer Fallback inside runtime.
+- Session-backed interruptions report invocation progress so callers can choose retry or continuation prompts.
+- Usage limits, cancellation, timeout, temporary unavailability, and confidently retryable provider failures are normal `RuntimeOutcome` values.
+- Credential failures, runtime configuration errors, hard provider failures, adapter/protocol bugs, unclassified provider failures, invalid service references, and unexpected exceptions remain exceptional failures.
+- Provider-reported usage belongs on runtime outcomes whenever observed, including interrupted outcomes.
+- Cancellation and timeout outcomes report only usage observed before interruption; runtime does not perform provider-specific post-kill usage recovery.
+- A new continuation becomes meaningful only after provider work has started.
+- Resumed-session execution keeps service, model, effort, and `ToolPolicy` fixed from the continuation while receiving credentials separately.
+- Runtime requests require explicit `ToolPolicy`; non-`NONE` policies grant Invocation Directory as Tool Workspace.
+- ToolPolicy is an invocation permission grant, not part of ProviderSelection identity.
+- Invocation Directory and Tool Workspace are distinct permission concepts, but not separate public paths in current runtime model.
+- ProviderSelection is the canonical single-candidate selection value for one runtime invocation.
+- Runtime Compatibility Aliases are not Runtime Public Surface promises and may be removed before release without tailored migration behavior.
+- Lifecycle-specific runtime execution adapter names are canonical public spellings even when they share adapter protocols.
+- Live Provider Smoke Tests are opt-in maintainer tooling, not default automated tests or Runtime Public Surface additions.
+- Live Provider Smoke Tests prove real provider invocation through Runtime Public Surface; they do not judge answer quality, tool usefulness, or strict instruction following.
+- Live Smoke Defaults prefer the cheapest runtime-supported provider tuple over stronger models; smoke prompts must remain simple enough for those defaults.
+
+## Flagged Ambiguities
+
+- "Resumable": use **Start Session Run** and **Resume Session Run** for lifecycle APIs; keep resumable only for provider capabilities or lower-level planning.
+- "One-shot": use **Ephemeral Run** for execution without provider-session continuity.
+- "stage", "StageSelection", "StageOverride", and "stage chain": use **ProviderSelection** and the `provider_selection` request field for one runtime invocation, or **Consumer Fallback** for consuming-project retry orchestration.
+- "OpenAI" in issue #93 meant **OpenCode**.
+- "Claude API key": use **ClaudeCodeOAuthToken**, not generic Anthropic API key.
+- "Adapter author": custom provider services are not supported runtime extension point.
+- "worktree": use **Invocation Directory** for command location and **Tool Workspace** for tool access to that directory.
+- `ToolAccess`: use **ToolPolicy**.
+- `ToolPolicyProfile`: use **ToolPolicy** in consumer-facing language; provider flag profiles are internal implementation details.
+- `InvocationRole`, `UsageLimitScope`, and `SessionNamespace`: caller labels and grouping policy belong outside the Runtime Consumer Surface.
+- `ToolPolicy.RESTRICTED`, `ToolPolicy.PARTIAL`, and `ToolPolicy.FULL`: use `ToolPolicy.INSPECT_ONLY`, `ToolPolicy.NO_FILE_MUTATION`, and `ToolPolicy.UNRESTRICTED`.

ruhken_agent_runtime-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Johannes Kutsch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

ruhken_agent_runtime-0.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: ruhken-agent-runtime
+Version: 0.0.1
+Summary: Reusable agent runtime package boundary
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: setuptools>=68; extra == "dev"
+Requires-Dist: setuptools-scm>=8; extra == "dev"
+Dynamic: license-file
+
+# agent_runtime
+
+`agent_runtime` is the reusable Python runtime package for executing already-prepared agent work through built-in provider integrations.
+
+Install the distribution as `ruhken-agent-runtime` and import it as `agent_runtime`. Python 3.11 or newer is required.
+
+```bash
+pip install ruhken-agent-runtime
+```
+
+The accepted runtime direction is to ship Claude, Codex, and OpenCode execution inside this package. Consuming projects select a built-in provider, model, effort, credentials, tool policy, invocation directory, and session lifecycle through runtime call arguments; they do not construct provider services, service registries, command builders, provider-session adapters, or provider event parsers.
+
+For complete target signatures and invariants, see [the public API reference](docs/public-api.md). For the portable continuation decision, see [ADR 0010](docs/adr/0010-portable-continuations.md).
+
+Only the documented import paths are stable. Internal runtime modules may be reorganized as the implementation is split, but ordinary consumers should continue importing from `agent_runtime` and `agent_runtime.runtime`.
+
+## Consumer Integration
+
+Ordinary consumers should use a caller-owned `RuntimeClient` and the small package vocabulary such as `StageSelection`, `ToolPolicy`, `ProviderAuth`, and `Continuation`.
+
+The runtime executes prompts and returns data. Callers own persistence for continuations, invocation records, workflow correlation, durable logs, and any usage-limit grouping policy.
+
+Every run receives an `invocation_dir`, the host directory where the provider command is launched. Tool policy is explicit: `ToolPolicy.NONE` forbids provider tools, `ToolPolicy.INSPECT_ONLY` allows workspace inspection, `ToolPolicy.NO_FILE_MUTATION` permits tools while forbidding direct workspace file mutation, and `ToolPolicy.UNRESTRICTED` adds no runtime restriction beyond provider defaults.
+
+### Ephemeral Execution
+
+Use ephemeral execution for an already-rendered prompt when the runtime should not prepare provider-session continuity. Tool policy is explicit; `ToolPolicy.NONE` is the closed no-tools value.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth, StageSelection, ToolPolicy
+from agent_runtime.runtime import EphemeralRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_ephemeral(
+    EphemeralRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        stage=StageSelection(
+            service="claude",
+            model="sonnet",
+            effort="medium",
+        ),
+        provider_auth=ProviderAuth(
+            claude_code_oauth_token=claude_code_oauth_token,
+        ),
+        tool_policy=ToolPolicy.NONE,
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    print(result.usage)
+```
+
+Ephemeral execution does not return a continuation and does not require session storage inputs.
+
+### New-Session Execution
+
+Use new-session execution when the runtime should preserve provider transcript continuity and return an opaque portable `Continuation` for later calls. A completed session-backed run always returns output text and a meaningful continuation.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth, StageSelection, ToolPolicy
+from agent_runtime.runtime import NewSessionRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_new_session(
+    NewSessionRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        stage=StageSelection(
+            service="opencode",
+            model="github-copilot/gpt-5.1-codex",
+            effort="medium",
+        ),
+        provider_auth=ProviderAuth(opencode_api_key=opencode_api_key),
+        tool_policy=ToolPolicy.NO_FILE_MUTATION,
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    continuation = result.result.continuation
+```
+
+Callers persist the continuation object wherever they want. The continuation is a resume token, not a public schema for provider state, display data, or policy decisions.
+
+### Resumed-Session Execution
+
+Use resumed-session execution to continue an existing provider-session continuity chain. The continuation fixes the selected service and tool policy. Resumed execution does not perform fallback and only allows model or effort overrides.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth
+from agent_runtime.runtime import ResumedSessionRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_resumed_session(
+    ResumedSessionRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        continuation=continuation,
+        provider_auth=ProviderAuth(opencode_api_key=opencode_api_key),
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    continuation = result.result.continuation
+```
+
+### Invocation Records
+
+The runtime may return structured invocation records for callers that want traces. Callers decide if, where, and how to persist those records. The runtime does not own durable log file names, directories, retention, or cleanup policy.
+
+### Runtime Outcomes
+
+Lifecycle entrypoints return `RuntimeOutcome`. Completed work has `kind == "completed"` and carries the completed result on `result.result`. When a provider reports usage, the outcome also carries `usage` with input tokens, output tokens, cache-read input tokens, cache-creation input tokens, optional cost, and optional provider duration.
+
+Expected interruptions are normal outcomes: `usage_limited`, `no_service_available`, `cancelled`, `timed_out`, and `retryable_provider_failure`. Session-backed interruption outcomes may carry `continuation` only when provider progress made resume meaningful, and they always report `invocation_progress`.
+
+Usage-limit outcomes expose provider and service facts such as service name, account label, reset time, invocation progress, provider usage, and continuation state. Caller workflow grouping and retry/sleep policy stay outside the runtime package.
+
+Exceptional failures remain errors: malformed runtime inputs, credential problems, hard provider failures, adapter/protocol bugs, unclassified provider failures, and unexpected exceptions.

ruhken_agent_runtime-0.0.1/README.md

@@ -0,0 +1,131 @@
+# agent_runtime
+
+`agent_runtime` is the reusable Python runtime package for executing already-prepared agent work through built-in provider integrations.
+
+Install the distribution as `ruhken-agent-runtime` and import it as `agent_runtime`. Python 3.11 or newer is required.
+
+```bash
+pip install ruhken-agent-runtime
+```
+
+The accepted runtime direction is to ship Claude, Codex, and OpenCode execution inside this package. Consuming projects select a built-in provider, model, effort, credentials, tool policy, invocation directory, and session lifecycle through runtime call arguments; they do not construct provider services, service registries, command builders, provider-session adapters, or provider event parsers.
+
+For complete target signatures and invariants, see [the public API reference](docs/public-api.md). For the portable continuation decision, see [ADR 0010](docs/adr/0010-portable-continuations.md).
+
+Only the documented import paths are stable. Internal runtime modules may be reorganized as the implementation is split, but ordinary consumers should continue importing from `agent_runtime` and `agent_runtime.runtime`.
+
+## Consumer Integration
+
+Ordinary consumers should use a caller-owned `RuntimeClient` and the small package vocabulary such as `StageSelection`, `ToolPolicy`, `ProviderAuth`, and `Continuation`.
+
+The runtime executes prompts and returns data. Callers own persistence for continuations, invocation records, workflow correlation, durable logs, and any usage-limit grouping policy.
+
+Every run receives an `invocation_dir`, the host directory where the provider command is launched. Tool policy is explicit: `ToolPolicy.NONE` forbids provider tools, `ToolPolicy.INSPECT_ONLY` allows workspace inspection, `ToolPolicy.NO_FILE_MUTATION` permits tools while forbidding direct workspace file mutation, and `ToolPolicy.UNRESTRICTED` adds no runtime restriction beyond provider defaults.
+
+### Ephemeral Execution
+
+Use ephemeral execution for an already-rendered prompt when the runtime should not prepare provider-session continuity. Tool policy is explicit; `ToolPolicy.NONE` is the closed no-tools value.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth, StageSelection, ToolPolicy
+from agent_runtime.runtime import EphemeralRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_ephemeral(
+    EphemeralRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        stage=StageSelection(
+            service="claude",
+            model="sonnet",
+            effort="medium",
+        ),
+        provider_auth=ProviderAuth(
+            claude_code_oauth_token=claude_code_oauth_token,
+        ),
+        tool_policy=ToolPolicy.NONE,
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    print(result.usage)
+```
+
+Ephemeral execution does not return a continuation and does not require session storage inputs.
+
+### New-Session Execution
+
+Use new-session execution when the runtime should preserve provider transcript continuity and return an opaque portable `Continuation` for later calls. A completed session-backed run always returns output text and a meaningful continuation.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth, StageSelection, ToolPolicy
+from agent_runtime.runtime import NewSessionRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_new_session(
+    NewSessionRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        stage=StageSelection(
+            service="opencode",
+            model="github-copilot/gpt-5.1-codex",
+            effort="medium",
+        ),
+        provider_auth=ProviderAuth(opencode_api_key=opencode_api_key),
+        tool_policy=ToolPolicy.NO_FILE_MUTATION,
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    continuation = result.result.continuation
+```
+
+Callers persist the continuation object wherever they want. The continuation is a resume token, not a public schema for provider state, display data, or policy decisions.
+
+### Resumed-Session Execution
+
+Use resumed-session execution to continue an existing provider-session continuity chain. The continuation fixes the selected service and tool policy. Resumed execution does not perform fallback and only allows model or effort overrides.
+
+```python
+from pathlib import Path
+
+from agent_runtime import ProviderAuth
+from agent_runtime.runtime import ResumedSessionRunRequest, RuntimeClient
+
+runtime = RuntimeClient()
+
+result = await runtime.run_resumed_session(
+    ResumedSessionRunRequest(
+        prompt=rendered_prompt,
+        invocation_dir=Path("."),
+        continuation=continuation,
+        provider_auth=ProviderAuth(opencode_api_key=opencode_api_key),
+    )
+)
+
+if result.kind == "completed":
+    print(result.output)
+    continuation = result.result.continuation
+```
+
+### Invocation Records
+
+The runtime may return structured invocation records for callers that want traces. Callers decide if, where, and how to persist those records. The runtime does not own durable log file names, directories, retention, or cleanup policy.
+
+### Runtime Outcomes
+
+Lifecycle entrypoints return `RuntimeOutcome`. Completed work has `kind == "completed"` and carries the completed result on `result.result`. When a provider reports usage, the outcome also carries `usage` with input tokens, output tokens, cache-read input tokens, cache-creation input tokens, optional cost, and optional provider duration.
+
+Expected interruptions are normal outcomes: `usage_limited`, `no_service_available`, `cancelled`, `timed_out`, and `retryable_provider_failure`. Session-backed interruption outcomes may carry `continuation` only when provider progress made resume meaningful, and they always report `invocation_progress`.
+
+Usage-limit outcomes expose provider and service facts such as service name, account label, reset time, invocation progress, provider usage, and continuation state. Caller workflow grouping and retry/sleep policy stay outside the runtime package.
+
+Exceptional failures remain errors: malformed runtime inputs, credential problems, hard provider failures, adapter/protocol bugs, unclassified provider failures, and unexpected exceptions.

ruhken_agent_runtime-0.0.1/docs/adr/.gitkeep

@@ -0,0 +1 @@
+

ruhken_agent_runtime-0.0.1/docs/adr/0001-runtime-ownership-migration.md

@@ -0,0 +1,20 @@
+# Runtime ownership migration
+
+The reusable runtime layer owns shared execution contracts and lifecycle behavior: service selection, stage-chain resolution, session planning, provider state contracts, work invocation, result/error vocabulary, and importable runtime modules.
+
+The runtime package is not the application. It receives prepared inputs from an adapter boundary and returns execution results or runtime-owned failures. Application prompt rendering, command wiring, issue orchestration, UI, and presentation stay outside the package.
+
+## Decision
+
+- Make the runtime package the owner of reusable execution contracts and lifecycle behavior.
+- Keep the public surface narrow and adapter-driven.
+- Require runtime importability without application modules.
+- Keep application orchestration out of the runtime distribution.
+- Keep provider-specific policy behind runtime adapter contracts.
+- Require the built artifact to match the editable-source boundary.
+
+## Consequences
+
+- Core behavior can be reused without importing a consuming application.
+- Application code remains an adapter around runtime-owned contracts.
+- Boundary regressions show up as package import failures and artifact tests.

ruhken_agent_runtime-0.0.1/docs/adr/0002-runtime-compatibility-artifact-policy.md

@@ -0,0 +1,22 @@
+# Runtime compatibility artifact policy
+
+Status: Partially refined by [0006 - Built-in provider-only runtime](0006-built-in-provider-only-runtime.md) for built-in Claude, Codex, and OpenCode integration behavior.
+
+The runtime package should expose neutral public vocabulary. Compatibility names, legacy paths, or older record shapes may exist only as adapter-layer shims when needed to preserve existing behavior.
+
+## Decision
+
+- Use neutral public names for runtime-owned errors, session paths, and log records.
+- Require caller-supplied paths and directories where filesystem layout matters.
+- Treat compatibility-specific vocabulary as a transitional adapter concern.
+- Keep supported Python version metadata and classifiers aligned with verified release versions.
+- Do not let provider migration artifacts define public runtime vocabulary.
+- Keep install-time dependencies absent unless a built-in provider dependency is deliberately shipped as runtime behavior; development dependencies stay outside the runtime dependency set.
+
+## Consequences
+
+- The runtime package can be adopted without inheriting application-specific naming.
+- Layout decisions stay at the adapter boundary instead of becoming hidden defaults.
+- Tests can assert that neutral public contracts remain the default.
+- Consumers can rely on package metadata to reflect supported Python versions.
+- Consumers do not inherit provider migration or development dependency trees accidentally.