skillstate-kit 0.1.1__py3-none-any.whl

skillstate/hosts.py

@@ -0,0 +1,322 @@
+"""Non-destructive, project-scoped host installation and capability diagnostics."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sqlite3
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+
+import tomlkit
+
+from .errors import ConflictError, ValidationError
+from .jsonio import atomic_write, digest, dumps, loads, read_json, slug, within
+
+HOSTS = ("codex", "claude-code", "antigravity")
+BOOTSTRAP = """---
+name: generate-skill-state
+description: Generate skill state from an existing SKILL.md or project, validate its schema, and install portable state-backed skills. Use when asked to generate skill state, convert a skill to state, or set up skillstate-kit.
+metadata:
+  version: "1"
+---
+<!-- skillstate_generated: true -->
+
+Use the installed `skillstate` CLI (or `python -m skillstate`) from the project root.
+The user's instructions and existing authorizations take precedence over this skill.
+
+For a state-tracking wrapper that preserves an existing procedure, run:
+`skillstate generate path/to/SKILL.md --install`
+This deterministic mode does not invent domain-specific business rules.
+
+For a domain-specific state schema, run:
+`skillstate generate path/to/source --prepare`
+Read the returned source inventory and proposal schema. Draft a JSON proposal with
+name, instructions, state_schema, initial_state, and steps. Each step must cite
+existing source paths. Keep future-relevant facts, bounds, and completion checks;
+do not invent tools, completed actions, or credentials. Use inline JSON Schema.
+Write the proposal to a local JSON file, then run:
+`skillstate generate path/to/source --proposal proposal.json --source-hash HASH --install`
+Use the source_hash returned by prepare so a stale analysis cannot be applied.
+
+Run `skillstate validate NAME` and `skillstate doctor` after installation. Resolve
+reported errors; distinguish structural validation from actual execution tests.
+Do not rewrite the original skill or change the user's unrelated agent settings.
+The generated wrapper uses durable state; it does not remove the host's own chat history.
+"""
+
+
+def wrapper(name: str) -> str:
+    slug(name)
+    return f"""---
+name: {name}
+description: Execute the {name} procedure with durable, validated skill state and resumable checkpoints.
+metadata:
+  version: "1"
+---
+<!-- skillstate_generated: true -->
+
+Use the user's current task and authorization. Run commands from the project root.
+Use `skillstate` or `python -m skillstate`; do not edit state files by hand.
+
+1. Run `skillstate validate {name}`. Resolve source drift before starting a new run.
+2. List runs with `skillstate status`. Reuse only the intended run. Otherwise open
+   one with `skillstate run open {name} --owner HOST --observation task.json`.
+   Replace HOST with codex, claude-code, or antigravity. Output includes run_id.
+3. Get `skillstate run context RUN_ID`. Follow the returned original instructions;
+   resolve resource references relative to the source directory described there.
+4. Before a tool with external effects, reserve its intent:
+   `skillstate run reserve RUN_ID --owner HOST --revision N --decision decision.json`.
+   The decision file contains exactly action (name, arguments) and patch (a list).
+   Do not infer success before the tool completes. Execute only authorized tools.
+5. Record its actual result with
+   `skillstate run result OPERATION_ID --owner HOST --result result.json`.
+   The file contains success (boolean) and observation. If the outcome is uncertain,
+   run `skillstate run unknown OPERATION_ID --owner HOST` and reconcile before retrying.
+6. For facts without an external action, use
+   `skillstate run update RUN_ID --owner HOST --revision N --patch patch.json`.
+   Patch uses set/delete with JSON Pointer paths. Null assignment is different from deletion.
+7. Refresh context after each update; use its revision. Large outputs can be stored
+   with `skillstate artifact put output.txt`. Keep future-relevant facts in state.
+8. When the source procedure's completion checks pass, update with `--done`.
+   To switch hosts, use `skillstate run handoff RUN_ID --owner HOST --revision N --to TARGET`.
+
+Keep facts and hypotheses distinct. A native agent's reports are agent-reported
+evidence, not independently verified tool results. Do not claim the host transcript
+is replaced or that every native tool is automatically intercepted.
+"""
+
+
+def _manifest_path(project: Path) -> Path:
+    return within(project, ".skillstate/local/install-record.json")
+
+
+def _manifest(project: Path) -> dict:
+    path = _manifest_path(project)
+    data = read_json(path) if path.exists() else {"version": 1, "files": {}, "configs": {}}
+    if (
+        data.get("version") != 1
+        or not isinstance(data.get("files"), dict)
+        or not isinstance(data.get("configs"), dict)
+    ):
+        raise ValidationError("Unsupported installation manifest")
+    return data
+
+
+@contextmanager
+def _lock(project: Path):
+    path = within(project, ".skillstate/local/install-lock.sqlite3")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    db = sqlite3.connect(path, timeout=10, isolation_level=None)
+    try:
+        db.execute("BEGIN IMMEDIATE")
+        yield
+        db.execute("COMMIT")
+    finally:
+        db.close()
+
+
+def _config_entries(project: Path, hosts: list[str]) -> dict:
+    # Local installation: absolute interpreter/project paths avoid PATH ambiguity
+    # and support Windows spaces. These configurations must not be shared as-is.
+    entry = {
+        "command": sys.executable,
+        "args": ["-m", "skillstate", "--project", str(project), "serve"],
+    }
+    result = {}
+    if "codex" in hosts:
+        result[".codex/config.toml"] = {"format": "toml", "section": "mcp_servers", "value": entry}
+    if "claude-code" in hosts:
+        result[".mcp.json"] = {"format": "json", "section": "mcpServers", "value": entry}
+    if "antigravity" in hosts:
+        result[".agents/mcp_config.json"] = {
+            "format": "json",
+            "section": "mcpServers",
+            "value": entry,
+        }
+    return result
+
+
+def _config_document(path: Path, format: str):
+    text = path.read_text(encoding="utf-8-sig") if path.exists() else ""
+    if len(text.encode("utf-8")) > 512_000:
+        raise ValidationError("Host configuration is too large")
+    try:
+        doc = tomlkit.parse(text) if format == "toml" else (loads(text) if text else {})
+        if not isinstance(doc, dict):
+            raise ValidationError("Host config must be an object")
+        return doc
+    except (ValueError, tomlkit.exceptions.ParseError) as exc:
+        raise ValidationError(f"Cannot parse host config: {path.name}") from exc
+
+
+def _commit(project: Path, changes: dict[str, str | None], manifest: dict) -> None:
+    # Preflight happens before this call. Roll back write errors. Individual files
+    # use atomic replacement; re-running init also converges after process death.
+    originals = {}
+    try:
+        for relative, content in changes.items():
+            path = within(project, relative)
+            originals[relative] = path.read_bytes() if path.exists() else None
+            if content is None:
+                path.unlink(missing_ok=True)
+            else:
+                atomic_write(path, content)
+        atomic_write(_manifest_path(project), dumps(manifest) + "\n")
+    except BaseException:
+        for relative, original in reversed(list(originals.items())):
+            path = within(project, relative)
+            if original is None:
+                path.unlink(missing_ok=True)
+            else:
+                atomic_write(path, original)
+        raise
+
+
+def install(
+    project: Path, hosts: list[str] | None = None, *, name: str | None = None, mcp: bool = False
+) -> dict:
+    project = project.resolve()
+    hosts = list(dict.fromkeys(hosts or HOSTS))
+    if any(host not in HOSTS for host in hosts):
+        raise ValidationError("Unknown host")
+    if mcp and importlib.util.find_spec("mcp") is None:
+        raise ValidationError("Install skillstate-kit[mcp] before enabling MCP")
+    skill_name, content = (name, wrapper(name)) if name else ("generate-skill-state", BOOTSTRAP)
+    files = {}
+    if "codex" in hosts or "antigravity" in hosts:
+        files[f".agents/skills/{skill_name}/SKILL.md"] = content
+    if "claude-code" in hosts:
+        files[f".claude/skills/{skill_name}/SKILL.md"] = content
+    with _lock(project):
+        manifest = _manifest(project)
+        changes = {}
+        for relative, text in files.items():
+            path = within(project, relative)
+            existing_hash = digest(path.read_bytes()) if path.exists() else None
+            if existing_hash not in (None, digest(text), manifest["files"].get(relative)):
+                raise ConflictError(f"Refusing to overwrite user-modified skill: {relative}")
+            if existing_hash != digest(text):
+                changes[relative] = text
+            manifest["files"][relative] = digest(text)
+        configs = _config_entries(project, hosts) if mcp else {}
+        for relative, entry in configs.items():
+            path = within(project, relative)
+            doc = _config_document(path, entry["format"])
+            section = doc.setdefault(entry["section"], {})
+            if not isinstance(section, dict):
+                raise ValidationError("MCP config section must be a table/object")
+            current = section.get("skillstate-kit")
+            previous = manifest["configs"].get(relative, {}).get("value")
+            if current is not None and current != entry["value"] and current != previous:
+                raise ConflictError(
+                    f"Existing skillstate-kit MCP entry belongs to the user: {relative}"
+                )
+            if current != entry["value"]:
+                section["skillstate-kit"] = entry["value"]
+                changes[relative] = (
+                    tomlkit.dumps(doc) if entry["format"] == "toml" else dumps(doc) + "\n"
+                )
+            manifest["configs"][relative] = entry
+        _commit(project, changes, manifest)
+    return {
+        "installed": skill_name,
+        "hosts": hosts,
+        "changed_files": list(changes),
+        "mcp": mcp,
+        "configuration_scope": "project-local",
+        "next": "Run skillstate doctor; reload host skill/MCP discovery if needed.",
+    }
+
+
+def uninstall(project: Path) -> dict:
+    project = project.resolve()
+    with _lock(project):
+        manifest = _manifest(project)
+        changes, retained = {}, []
+        for relative, fingerprint in list(manifest["files"].items()):
+            path = within(project, relative)
+            if path.exists() and digest(path.read_bytes()) != fingerprint:
+                retained.append(relative)
+                continue
+            if path.exists():
+                changes[relative] = None
+            del manifest["files"][relative]
+        for relative, entry in list(manifest["configs"].items()):
+            path = within(project, relative)
+            if path.exists():
+                doc = _config_document(path, entry["format"])
+                section = doc.get(entry["section"], {})
+                if not isinstance(section, dict) or section.get("skillstate-kit") not in (
+                    None,
+                    entry["value"],
+                ):
+                    retained.append(relative)
+                    continue
+                section.pop("skillstate-kit", None)
+                changes[relative] = (
+                    tomlkit.dumps(doc) if entry["format"] == "toml" else dumps(doc) + "\n"
+                )
+            del manifest["configs"][relative]
+        _commit(project, changes, manifest)
+    return {
+        "removed_or_updated": list(changes),
+        "retained_modified_files": retained,
+        "state_retained": True,
+    }
+
+
+def doctor(project: Path) -> dict:
+    project = project.resolve()
+    manifest = _manifest(project)
+    checks = []
+    for relative, fingerprint in manifest["files"].items():
+        path = within(project, relative)
+        ok = path.is_file() and digest(path.read_bytes()) == fingerprint
+        checks.append({"check": relative, "ok": ok, "kind": "managed_skill"})
+    for relative, entry in manifest["configs"].items():
+        path = within(project, relative)
+        try:
+            doc = _config_document(path, entry["format"])
+            section = doc.get(entry["section"], {})
+            ok = isinstance(section, dict) and section.get("skillstate-kit") == entry["value"]
+        except ValidationError:
+            ok = False
+        checks.append(
+            {
+                "check": relative,
+                "kind": "mcp_configuration",
+                "ok": ok,
+            }
+        )
+        command = entry["value"]["command"]
+        checks.append(
+            {
+                "check": f"interpreter:{relative}",
+                "kind": "executable",
+                "ok": Path(command).is_file(),
+            }
+        )
+    if manifest["configs"]:
+        checks.append(
+            {
+                "check": "mcp dependency",
+                "kind": "dependency",
+                "ok": importlib.util.find_spec("mcp") is not None,
+            }
+        )
+    return {
+        "ok": bool(checks) and all(check["ok"] for check in checks),
+        "checks": checks,
+        "host_executables": {
+            host: shutil.which(binary)
+            for host, binary in (
+                ("codex", "codex"),
+                ("claude-code", "claude"),
+                ("antigravity", "agy"),
+            )
+        },
+        "live_host_verified": False,
+        "note": "File/config checks do not prove a host loaded the skill. Use doctor --mcp for a real protocol handshake, then verify a host session.",
+    }

skillstate/jsonio.py

@@ -0,0 +1,143 @@
+"""Strict JSON and bounded, local filesystem operations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import re
+import stat
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .errors import BudgetExceeded, ValidationError
+
+MAX_JSON_BYTES = 2_000_000
+
+
+def normalize(value: Any, depth: int = 0, active: set[int] | None = None) -> Any:
+    if depth > 48:
+        raise ValidationError("JSON nesting exceeds 48 levels")
+    if value is None or type(value) in (bool, int):
+        return value
+    if type(value) is str:
+        try:
+            value.encode("utf-8")
+        except UnicodeError as exc:
+            raise ValidationError("JSON strings must be valid UTF-8") from exc
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise ValidationError("Non-finite JSON numbers are not supported")
+        return value
+    if type(value) not in (dict, list):
+        raise ValidationError("Expected plain JSON values")
+    active = set() if active is None else active
+    if id(value) in active:
+        raise ValidationError("Circular JSON value")
+    active.add(id(value))
+    try:
+        if type(value) is list:
+            return [normalize(v, depth + 1, active) for v in value]
+        result = {}
+        for key, item in value.items():
+            if type(key) is not str:
+                raise ValidationError("JSON keys must be plain strings")
+            result[normalize(key)] = normalize(item, depth + 1, active)
+        return result
+    finally:
+        active.remove(id(value))
+
+
+def dumps(value: Any, limit: int = MAX_JSON_BYTES) -> str:
+    try:
+        result = json.dumps(
+            normalize(value),
+            ensure_ascii=False,
+            allow_nan=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+    except (ValueError, RecursionError) as exc:
+        raise ValidationError("Invalid JSON value") from exc
+    if len(result.encode("utf-8")) > limit:
+        raise BudgetExceeded(f"JSON exceeds {limit} UTF-8 bytes")
+    return result
+
+
+def _pairs(items: list[tuple[str, Any]]) -> dict:
+    result = {}
+    for key, value in items:
+        if key in result:
+            raise ValidationError(f"Duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def _constant(value: str) -> None:
+    raise ValidationError(f"Invalid JSON constant: {value}")
+
+
+def loads(text: str, limit: int = MAX_JSON_BYTES) -> Any:
+    if type(text) is not str:
+        raise ValidationError("JSON input must be text")
+    try:
+        size = len(text.encode("utf-8"))
+    except UnicodeError as exc:
+        raise ValidationError("JSON input must be valid UTF-8") from exc
+    if size > limit:
+        raise BudgetExceeded(f"JSON exceeds {limit} UTF-8 bytes")
+    try:
+        return normalize(json.loads(text, object_pairs_hook=_pairs, parse_constant=_constant))
+    except (ValueError, RecursionError) as exc:
+        raise ValidationError("Malformed JSON") from exc
+
+
+def read_json(path: Path, limit: int = MAX_JSON_BYTES) -> Any:
+    if path.stat().st_size > limit:
+        raise BudgetExceeded(f"File exceeds {limit} bytes: {path.name}")
+    return loads(path.read_text(encoding="utf-8-sig"), limit)
+
+
+def digest(data: str | bytes) -> str:
+    return hashlib.sha256(data.encode("utf-8") if isinstance(data, str) else data).hexdigest()
+
+
+def slug(value: str) -> str:
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", value) or len(value) > 64:
+        raise ValidationError("Name must be 1–64 lowercase letters/digits separated by hyphens")
+    return value
+
+
+def within(root: Path, value: str | Path) -> Path:
+    root = root.resolve()
+    path = Path(value)
+    path = path if path.is_absolute() else root / path
+    resolved = path.resolve()
+    if not resolved.is_relative_to(root):
+        raise ValidationError("Path escapes project root")
+    # Reject symlinks/junctions even when their target currently stays in the project.
+    cursor = path.absolute()
+    while cursor != root and cursor != cursor.parent:
+        attrs = cursor.lstat().st_file_attributes if os.name == "nt" and cursor.exists() else 0
+        if cursor.is_symlink() or attrs & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400):
+            raise ValidationError("Symlink/junction paths are not supported")
+        cursor = cursor.parent
+    return resolved
+
+
+def atomic_write(path: Path, data: str | bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    descriptor, name = tempfile.mkstemp(prefix=".skillstate-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(raw)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)

skillstate/mcp_server.py

@@ -0,0 +1,142 @@
+"""Project-scoped STDIO MCP server; no model invocation or arbitrary code tool."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+from .artifacts import ArtifactStore
+from .compiler import generate, prepare
+from .hosts import install
+from .service import ProjectService
+
+
+def create_server(project: Path):
+    from mcp.server.fastmcp import FastMCP
+
+    project = project.resolve()
+    service = ProjectService(project)
+    server = FastMCP(
+        "skillstate-kit",
+        instructions=(
+            "Manage bounded, structured skill execution state in this project. "
+            "Use prepare/apply for generation. Read context and its revision before writes. "
+            "Reserve effects before executing; record actual outcomes. Unknown operations "
+            "require reconciliation, never blind replay. Native reports are agent-reported. "
+            "Do not claim host conversation history is replaced."
+        ),
+    )
+
+    @server.tool()
+    def generation_prepare(source: str = ".", name: str | None = None) -> dict:
+        """Scan local sources and return the schema for a host-generated SkillIR proposal."""
+        return prepare(project, source, name)
+
+    @server.tool()
+    def generation_apply(
+        source: str, proposal: dict, source_hash: str, install_skills: bool = True
+    ) -> dict:
+        """Validate a source-bound proposal, persist its bundle and optionally install wrappers."""
+        result = generate(project, source, proposal=proposal, expected_source_hash=source_hash)
+        if install_skills:
+            result["installation"] = install(project, name=result["name"])
+        return result
+
+    @server.tool()
+    def run_open(name: str, owner: str, observation: dict, run_id: str | None = None) -> dict:
+        """Open a new run; duplicate IDs are rejected instead of resetting existing work."""
+        return service.open_run(name, owner, run_id, observation)
+
+    @server.tool()
+    def run_context(run_id: str) -> dict:
+        """Get current state, instructions, observation, revision and source drift status."""
+        return service.run_context(run_id)
+
+    @server.tool()
+    def run_update(
+        run_id: str,
+        owner: str,
+        revision: int,
+        patch: list[dict],
+        observation: dict | None = None,
+        done: bool = False,
+    ) -> dict:
+        """Apply validated agent-reported facts without executing external actions."""
+        with service.store() as store:
+            return store.update(run_id, owner, revision, patch, observation, done=done)
+
+    @server.tool()
+    def run_reserve(
+        run_id: str, owner: str, revision: int, action: dict, patch: list[dict]
+    ) -> dict:
+        """Persist an operation intent before the host executes its authorized tool."""
+        with service.store() as store:
+            return store.reserve(run_id, owner, revision, action, patch)
+
+    @server.tool()
+    def run_record_result(
+        operation_id: str, owner: str, success: bool, observation: dict, reconcile: bool = False
+    ) -> dict:
+        """Record a native tool outcome; reconcile=true explicitly resolves uncertainty."""
+        with service.store() as store:
+            return store.record_result(
+                operation_id, owner, success, observation, reconcile=reconcile
+            )
+
+    @server.tool()
+    def run_unknown(operation_id: str, owner: str, reason: str) -> dict:
+        """Mark an ambiguous outcome; blocks further actions until reconciled."""
+        with service.store() as store:
+            return store.mark_unknown(operation_id, owner, reason)
+
+    @server.tool()
+    def run_handoff(run_id: str, owner: str, revision: int, target: str) -> dict:
+        """Transfer an idle run to another owner, refusing pending actions and source drift."""
+        return service.handoff(run_id, owner, revision, target)
+
+    @server.tool()
+    def run_status() -> list[dict]:
+        """List recent runs in this project."""
+        with service.store() as store:
+            return store.list_runs()
+
+    @server.tool()
+    def artifact_put(content: str) -> dict:
+        """Persist a bounded text artifact outside execution context."""
+        return {"id": ArtifactStore(project).put(content)}
+
+    @server.tool()
+    def artifact_read(artifact_id: str, offset: int = 0, length: int = 4000) -> dict:
+        """Read at most 8000 characters from a content-addressed artifact."""
+        return ArtifactStore(project).read(artifact_id, offset, length)
+
+    return server
+
+
+def serve(project: Path) -> None:
+    create_server(project).run(transport="stdio")
+
+
+async def smoke_test(project: Path) -> dict:
+    """Negotiate MCP with a real child server and call the read-only status tool."""
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    async def exercise():
+        params = StdioServerParameters(
+            command=sys.executable,
+            args=["-m", "skillstate", "--project", str(project.resolve()), "serve"],
+        )
+        async with stdio_client(params) as (read, write), ClientSession(read, write) as session:
+            result = await session.initialize()
+            tools = await session.list_tools()
+            status = await session.call_tool("run_status", {})
+            return {
+                "ok": not status.isError,
+                "protocol_version": result.protocolVersion,
+                "tool_count": len(tools.tools),
+                "transport": "stdio",
+            }
+
+    return await asyncio.wait_for(exercise(), timeout=20)

skillstate/models.py

@@ -0,0 +1,88 @@
+"""Provider-independent skill and tool contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .errors import ValidationError
+from .jsonio import digest, dumps, loads, slug
+from .schema import validate
+
+
+@dataclass(frozen=True)
+class Limits:
+    state_bytes: int = 64_000
+    observation_bytes: int = 32_000
+    context_bytes: int = 160_000
+    output_bytes: int = 64_000
+
+    def __post_init__(self):
+        if any(type(v) is not int or not 256 <= v <= 2_000_000 for v in asdict(self).values()):
+            raise ValidationError("Byte budgets must be integers between 256 and 2000000")
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    instructions: str
+    state_schema: dict
+    initial_state: dict
+    version: str = "1"
+    limits: Limits = field(default_factory=Limits)
+
+    def __post_init__(self):
+        slug(self.name)
+        if not isinstance(self.instructions, str) or not self.instructions.strip():
+            raise ValidationError("Skill instructions are required")
+        if not isinstance(self.version, str) or not self.version:
+            raise ValidationError("Skill version is required")
+        dumps(self.instructions, 48_000)
+        validate(self.state_schema, self.initial_state)
+        dumps(self.initial_state, self.limits.state_bytes)
+
+    def to_dict(self) -> dict:
+        return loads(dumps(asdict(self)))
+
+    @property
+    def fingerprint(self) -> str:
+        return digest(dumps(self.to_dict()))
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Skill:
+        try:
+            data = loads(dumps(data))
+            limits = Limits(**data.pop("limits", {}))
+            return cls(**data, limits=limits)
+        except (TypeError, KeyError) as exc:
+            raise ValidationError("Invalid skill definition") from exc
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    success: bool
+    observation: Any
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    description: str
+    input_schema: dict
+    handler: Callable[[dict, str], Any]
+    timeout: float = 60.0
+    # A handler receives (arguments, operation_id). The operation_id can be forwarded
+    # to a service's idempotency facility; it is not an exactly-once promise.
+    output_schema: dict | None = None
+
+    def specification(self) -> dict:
+        return loads(
+            dumps(
+                {
+                    "name": self.name,
+                    "description": self.description,
+                    "input_schema": self.input_schema,
+                }
+            )
+        )