agentshim 0.14.0__tar.gz → 0.15.0__tar.gz

{agentshim-0.14.0 → agentshim-0.15.0}/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.15.0 (2026-10-09)
+
+### Added
+
+- Session tier. `Agent(provider, *, permissions, approvals, ...)` hands out
+  `Session`s: `prepare_turn(request, *, expect_conversation=None, pin=False) ->
+  TurnTicket` (the turn id exists before dispatch), `run(ticket, *, on_event=None)
+  -> Turn(result, continuity, turn_id, conversation_id)`, `interrupt()`,
+  `release()`, `adopt()`, `close()`. `Continuity` is `CONTINUED`, `RESET` or
+  `REPLACED`. Recovery is a pure `SessionPolicy` state machine: transient
+  retries on `RetryPolicy(delays)`, one fresh retry of a refused resume, a
+  backstop that forgets a resumed conversation after an unclassified failure,
+  renewal by `ProviderProfile.renewal` (`RenewalBudget`; Codex: 2 turns,
+  10M input tokens or 600 s), idle release, and checkpoints through
+  `CheckpointStore` / `InMemoryCheckpointStore` / `Checkpoint`.
+- Transport tier. `Transport.open(ConversationSpec) -> Conversation` with
+  `turn`, `interrupt`, `close`; `OneShotTransport` wraps the one-shot path
+  (bypass permissions only) and behaves exactly like `AgentSession`.
+  `CliAgent.derive(model=, event_handler=)` copies a checked agent.
+- Errors: `TurnFailedError(kind, detail)` (now the base of `CliExitError`),
+  `TurnTimeoutError` (now the base of `CliTimeoutError`), `ContinuityError`,
+  `SessionStateError`, `TurnCancelledError`. Session code catches the base
+  types only.
+- Events `TurnInterrupted` and `ApprovalDenied(kind, detail)`;
+  `TurnResult.interrupted` (default `False`).
+- Test doubles `FakeTransport`, `FakeConversation`, `FakeTurn`,
+  `FakeCheckpointStore`, `fake_profile`, `turn_failed`, `resume_refused`,
+  `turn_timeout`, and contract suites `TransportContract`,
+  `ConversationContract`, `CheckpointStoreContract`.
+- Docs: [sessions](https://vic-lsh.github.io/agentshim/sessions/).
+
+### Added (process layer)
+
+- MIT license (`LICENSE`), declared in the package metadata.
+- Long-lived processes: `CommandExecutor.spawn(SpawnRequest) -> Process` with a
+  pull-based output model (`StdoutLine`, `StderrLine`, `ProcessExited`),
+  implemented by `HostCommandExecutor` and `TransformingExecutor`.
+  `ProcessClosedError` reports a write to a closed or exited process.
+- `Confinement` protocol, `confine(executor, confinement)` and
+  `DockerExecConfinement` (`docker exec` into a running container, with path
+  mapping and `reap()` of marked processes).
+- `Clock`/`SystemClock`/`StopSignal` and `IdAllocator`/`RandomIds`.
+- `NativeMode`, `NativePermissions`, `ApprovalPolicy` and
+  `ProviderProfile.native_permission_modes` (default `BYPASS` only).
+- Test doubles `FakeProcess`, `FakePeer`, `EchoPeer`, `SilentPeer`,
+  `ReplayGates`, `GateMarker`, `FakeConfinement`, `FakeClock`, `SequentialIds`,
+  `FakeExecutor(peers=...)`, and contract suites `ProcessContract`,
+  `ConfinementContract`, `ClockContract` in `agentshim.testing.contracts`.
+- Generated, typed Codex `app-server` protocol (`agentshim.providers.codex.app_server`):
+  frozen dataclasses for the requests, notifications, server requests and item
+  types a transport needs, tolerant `from_wire` for server messages, strict
+  `to_wire` for client messages, and `parse_server_message`. Regenerated from
+  the CLI's own JSON Schema by `scripts/generate_codex_protocol.py` (codex-cli
+  0.160.0); not exported from the top-level package yet.
+
+### Fixed
+
+- `DockerExecConfinement.reap()` raises the new `ReapError` unless the
+  container is gone or stopped, and the reap script fails when the container
+  lacks `tr`/`grep`, instead of reporting a clean sweep. `env` may not use the
+  reserved `AGENTSHIM_CONFINED` name.
+- `Process.next_output(0)` on the host polls and returns already-queued output.
+
+## 0.14.1 (2026-10-04)
+
+### Fixed
+
+- Schema normalization preserves descriptions, titles and examples, including
+  annotations alongside `$ref`, so structured-output field guidance reaches
+  the model. Only metadata rejected by the selected dialect is removed.
+- The open schema dialect accepts `oneOf` variants, as Claude does.
+
 ## 0.14.0 (2026-10-04)
 
 Codex resumed turns report invocation usage. Additive.

agentshim-0.15.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vic Shihang Li
+
+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.

{agentshim-0.14.0 → agentshim-0.15.0}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.14.0
+Version: 0.15.0
 Summary: Provider-agnostic coding-agent CLI shims
+License-Expression: MIT
+License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: tomli>=2; python_full_version < '3.11'
 Provides-Extra: test
@@ -248,3 +250,7 @@ uv publish        # release
 
 uv run --group docs mkdocs build --strict
 ```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{agentshim-0.14.0 → agentshim-0.15.0}/README.md

@@ -238,3 +238,7 @@ uv publish        # release
 
 uv run --group docs mkdocs build --strict
 ```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{agentshim-0.14.0 → agentshim-0.15.0}/agentshim/__init__.py

@@ -11,21 +11,32 @@ from .core import (
     AgentEvent,
     AgentEventHandler,
     AgentShimError,
+    ApprovalDenied,
+    ApprovalPolicy,
     ArgvContext,
     AssistantText,
+    Checkpoint,
+    CheckpointStore,
     CliCheckError,
     CliExitError,
     CliNotFoundError,
     CliTimeoutError,
+    Clock,
     CompositeEventHandler,
     ConfigFileInstallation,
     ConfigScope,
     ConsoleEventHandler,
     ContextualStreamParser,
+    Continuity,
+    ContinuityError,
+    Conversation,
+    ConversationSpec,
     EventHandlerBase,
     FailureKind,
     FlagsInstallation,
     HttpMcpServer,
+    IdAllocator,
+    InMemoryCheckpointStore,
     Lifecycle,
     McpConfigError,
     McpInstallation,
@@ -34,26 +45,37 @@ from .core import (
     McpServer,
     McpTransport,
     ModelPricing,
+    NativeMode,
+    NativePermissions,
     NoopInstallation,
     NullEventHandler,
     OutputSchema,
     OutputSchemaStyle,
     ParsedTurn,
     ParserContext,
+    PolicyConfig,
     PricingTable,
+    ProcessClosedError,
     Provider,
     ProviderCapabilityError,
     ProviderError,
     ProviderProfile,
     ProviderUsage,
+    RandomIds,
     RawOutput,
+    ReapError,
     Reasoning,
+    RenewalBudget,
+    RetryPolicy,
     RunFinished,
     RunStarted,
     SchemaDialect,
     SchemaDialectError,
+    SessionPolicy,
     SessionResumeError,
     SessionStarted,
+    SessionState,
+    SessionStateError,
     SkillInvoked,
     SkillScope,
     SkillsDiscovered,
@@ -62,14 +84,21 @@ from .core import (
     SkillTracker,
     Stderr,
     StdioMcpServer,
+    StopSignal,
     StreamParser,
+    SystemClock,
     TokenUsage,
     TokenWeights,
     ToolCall,
     ToolResult,
     ToolTracker,
+    Transport,
+    TurnCancelledError,
+    TurnFailedError,
+    TurnInterrupted,
     TurnRequest,
     TurnResult,
+    TurnTimeoutError,
     UsageReport,
     compact_json,
     compose_event_handlers,
@@ -92,27 +121,45 @@ from .execution import (
     CommandRequest,
     CommandResult,
     CommandStreamSink,
+    Confinement,
+    DockerExecConfinement,
     HostCommandExecutor,
+    HostProcess,
     NullSink,
+    Process,
+    ProcessExited,
+    ProcessOutput,
+    SpawnRequest,
+    StderrLine,
+    StdoutLine,
     TransformingExecutor,
+    confine,
 )
+from .oneshot import OneShotTransport
 from .providers import get_provider, provider_names
 from .providers.claude import ClaudeHook, ClaudeProvider, SandboxConfig
 from .providers.codex import CodexProvider, CodexSandboxConfig
 from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
+from .runtime import Agent
+from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 __all__ = [
+    "Agent",
     "AgentEvent",
     "AgentEventHandler",
     "AgentSession",
     "AgentShimError",
+    "ApprovalDenied",
+    "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
     "CallbackCommandStreamSink",
+    "Checkpoint",
+    "CheckpointStore",
     "ClaudeHook",
     "ClaudeProvider",
     "CliAgent",
@@ -120,6 +167,7 @@ __all__ = [
     "CliExitError",
     "CliNotFoundError",
     "CliTimeoutError",
+    "Clock",
     "CodexProvider",
     "CodexSandboxConfig",
     "CommandExecutor",
@@ -130,15 +178,24 @@ __all__ = [
     "CompositeEventHandler",
     "ConfigFileInstallation",
     "ConfigScope",
+    "Confinement",
     "ConsoleEventHandler",
     "ContextualStreamParser",
+    "Continuity",
+    "ContinuityError",
+    "Conversation",
+    "ConversationSpec",
     "CopilotProvider",
+    "DockerExecConfinement",
     "EventHandlerBase",
     "FailureKind",
     "FlagsInstallation",
     "GeminiProvider",
     "HostCommandExecutor",
+    "HostProcess",
     "HttpMcpServer",
+    "IdAllocator",
+    "InMemoryCheckpointStore",
     "Lifecycle",
     "McpConfigError",
     "McpInstallation",
@@ -147,56 +204,86 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "NativeMode",
+    "NativePermissions",
     "NoopInstallation",
     "NullEventHandler",
     "NullSink",
+    "OneShotTransport",
     "OpencodeProvider",
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
     "ParserContext",
+    "PolicyConfig",
     "PricingTable",
+    "Process",
+    "ProcessClosedError",
+    "ProcessExited",
+    "ProcessOutput",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
     "ProviderProfile",
     "ProviderUsage",
+    "RandomIds",
     "RawOutput",
+    "ReapError",
     "Reasoning",
+    "RenewalBudget",
+    "RetryPolicy",
     "RunFinished",
     "RunStarted",
     "SandboxConfig",
     "SchemaDialect",
     "SchemaDialectError",
+    "Session",
+    "SessionPolicy",
     "SessionResumeError",
     "SessionStarted",
+    "SessionState",
+    "SessionStateError",
     "SkillInvoked",
     "SkillScope",
     "SkillSignal",
     "SkillSummary",
     "SkillTracker",
     "SkillsDiscovered",
+    "SpawnRequest",
     "Stderr",
+    "StderrLine",
     "StdioMcpServer",
+    "StdoutLine",
+    "StopSignal",
     "StreamParser",
+    "SystemClock",
     "TokenUsage",
     "TokenWeights",
     "ToolCall",
     "ToolResult",
     "ToolTracker",
     "TransformingExecutor",
+    "Transport",
+    "Turn",
+    "TurnCancelledError",
+    "TurnFailedError",
+    "TurnInterrupted",
     "TurnRequest",
     "TurnResult",
+    "TurnTicket",
+    "TurnTimeoutError",
     "UsageReport",
     "__version__",
     "compact_json",
     "compose_event_handlers",
+    "confine",
     "cost_usd",
     "default_pricing",
     "dialect_problems",
     "get_provider",
     "install_config_file",
     "interactive_env",
+    "map_mcp_servers",
     "materialize",
     "normalize",
     "normalized_usage",

{agentshim-0.14.0 → agentshim-0.15.0}/agentshim/agent.py

@@ -7,6 +7,7 @@ neither of them has to know that agents exist.
 
 from __future__ import annotations
 
+import copy
 import posixpath
 import threading
 import time
@@ -116,6 +117,19 @@ class CliAgent:
         self.executor.check_binary(self.binary_path, self.env, timeout=check_timeout)
         self.log(f"{self.profile.display_name} ready at {self.binary_path}")
 
+    def derive(self, *, model: str | None, event_handler: AgentEventHandler) -> CliAgent:
+        """Return a copy that uses *model* and reports events to *event_handler*.
+
+        The binary lookup and health check are not repeated: the copy shares
+        the executor, environment and resolved binary of this agent. That is
+        what lets one checked install serve many conversations, each with its
+        own event routing.
+        """
+        clone = copy.copy(self)
+        clone.model = model
+        clone.event_handler = event_handler
+        return clone
+
     def start_session(  # noqa: PLR0913 - one keyword per independent session option
         self,
         *,

{agentshim-0.14.0 → agentshim-0.15.0}/agentshim/core/__init__.py

@@ -7,6 +7,9 @@ this package may not do.
 
 from __future__ import annotations
 
+from .checkpoints import Checkpoint, CheckpointStore, InMemoryCheckpointStore
+from .clock import Clock, StopSignal, SystemClock
+from .conversation import Conversation, ConversationSpec, Transport
 from .env import interactive_env
 from .errors import (
     AgentShimError,
@@ -14,15 +17,23 @@ from .errors import (
     CliExitError,
     CliNotFoundError,
     CliTimeoutError,
+    ContinuityError,
     FailureKind,
     McpConfigError,
+    ProcessClosedError,
     ProviderCapabilityError,
+    ReapError,
     SchemaDialectError,
     SessionResumeError,
+    SessionStateError,
+    TurnCancelledError,
+    TurnFailedError,
+    TurnTimeoutError,
 )
 from .events import (
     AgentEvent,
     AgentEventHandler,
+    ApprovalDenied,
     AssistantText,
     CompositeEventHandler,
     ConsoleEventHandler,
@@ -40,10 +51,12 @@ from .events import (
     Stderr,
     ToolCall,
     ToolResult,
+    TurnInterrupted,
     UsageReport,
     compose_event_handlers,
 )
 from .home import prepare_config_home
+from .ids import IdAllocator, RandomIds
 from .mcp import (
     ConfigFileInstallation,
     FlagsInstallation,
@@ -54,6 +67,7 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
+from .permissions import ApprovalPolicy, NativeMode, NativePermissions
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
     ConfigScope,
@@ -61,6 +75,7 @@ from .profile import (
     McpScope,
     OutputSchemaStyle,
     ProviderProfile,
+    RenewalBudget,
     SchemaDialect,
     SkillScope,
     SkillSignal,
@@ -75,6 +90,7 @@ from .provider import (
     StreamParser,
 )
 from .schema import compact_json, dialect_problems, materialize, normalize
+from .session_policy import Continuity, PolicyConfig, RetryPolicy, SessionPolicy, SessionState
 from .skills import SkillSummary, SkillTracker
 from .stream import ToolTracker, parse_json_object
 from .turn import OutputSchema, TurnRequest, TurnResult
@@ -84,21 +100,32 @@ __all__ = [
     "AgentEvent",
     "AgentEventHandler",
     "AgentShimError",
+    "ApprovalDenied",
+    "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
+    "Checkpoint",
+    "CheckpointStore",
     "CliCheckError",
     "CliExitError",
     "CliNotFoundError",
     "CliTimeoutError",
+    "Clock",
     "CompositeEventHandler",
     "ConfigFileInstallation",
     "ConfigScope",
     "ConsoleEventHandler",
     "ContextualStreamParser",
+    "Continuity",
+    "ContinuityError",
+    "Conversation",
+    "ConversationSpec",
     "EventHandlerBase",
     "FailureKind",
     "FlagsInstallation",
     "HttpMcpServer",
+    "IdAllocator",
+    "InMemoryCheckpointStore",
     "Lifecycle",
     "McpConfigError",
     "McpInstallation",
@@ -107,26 +134,37 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "NativeMode",
+    "NativePermissions",
     "NoopInstallation",
     "NullEventHandler",
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
     "ParserContext",
+    "PolicyConfig",
     "PricingTable",
+    "ProcessClosedError",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
     "ProviderProfile",
     "ProviderUsage",
+    "RandomIds",
     "RawOutput",
+    "ReapError",
     "Reasoning",
+    "RenewalBudget",
+    "RetryPolicy",
     "RunFinished",
     "RunStarted",
     "SchemaDialect",
     "SchemaDialectError",
+    "SessionPolicy",
     "SessionResumeError",
     "SessionStarted",
+    "SessionState",
+    "SessionStateError",
     "SkillInvoked",
     "SkillScope",
     "SkillSignal",
@@ -135,14 +173,21 @@ __all__ = [
     "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
+    "StopSignal",
     "StreamParser",
+    "SystemClock",
     "TokenUsage",
     "TokenWeights",
     "ToolCall",
     "ToolResult",
     "ToolTracker",
+    "Transport",
+    "TurnCancelledError",
+    "TurnFailedError",
+    "TurnInterrupted",
     "TurnRequest",
     "TurnResult",
+    "TurnTimeoutError",
     "UsageReport",
     "compact_json",
     "compose_event_handlers",

agentshim-0.15.0/agentshim/core/checkpoints.py

@@ -0,0 +1,67 @@
+"""Durable record of which provider conversation a session was in.
+
+A checkpoint is what a restarted process needs to continue a conversation: the
+provider's id for it and the usage baseline of its last report. Where it is
+stored is the caller's business, so the store is a protocol.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from .usage import ProviderUsage
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    """A provider conversation a later process can resume.
+
+    ``usage`` is the conversation's most recent report, kept so a provider
+    whose usage is cumulative can still tell the next turn's increment.
+    """
+
+    conversation_id: str
+    usage: ProviderUsage | None = None
+
+
+class CheckpointStore(Protocol):
+    """Where a session keeps its checkpoint between processes."""
+
+    def load(self, key: str) -> Checkpoint | None:
+        """Return the checkpoint saved under *key*, or ``None``."""
+        ...
+
+    def save(self, key: str, checkpoint: Checkpoint) -> None:
+        """Replace whatever is saved under *key*."""
+        ...
+
+    def clear(self, key: str) -> None:
+        """Forget *key*; clearing a key that holds nothing is not an error."""
+        ...
+
+
+class InMemoryCheckpointStore:
+    """A ``CheckpointStore`` that lives and dies with the process."""
+
+    def __init__(self) -> None:
+        """Start empty."""
+        self._lock = threading.Lock()
+        self._items: dict[str, Checkpoint] = {}
+
+    def load(self, key: str) -> Checkpoint | None:
+        """Return the checkpoint saved under *key*, or ``None``."""
+        with self._lock:
+            return self._items.get(key)
+
+    def save(self, key: str, checkpoint: Checkpoint) -> None:
+        """Replace whatever is saved under *key*."""
+        with self._lock:
+            self._items[key] = checkpoint
+
+    def clear(self, key: str) -> None:
+        """Forget *key*."""
+        with self._lock:
+            self._items.pop(key, None)