Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,24 @@ inventory to ordered hashed plan parts, their allocation rows, and aggregate
coverage. `bind_plan_set` records hashed content evidence rather than command
lines; aggregate coverage is decided only by the server-side
`plan_set_coverage` preflight. Consumers receive verified preflight evidence,
never the artifact itself, and the sealed state is authenticated inside the
canonical authority digest.
never the artifact itself. The canonical authority digest is an unkeyed integrity
hash covering the sealed state; it does not establish server issuance.

For recipe admission, the `PlanSetMaterializer` service held by `ToolContext`
retains each successful bind's root and issued digest for that execution and
authority path. The default implementation, `DefaultPlanSetMaterializer`, stores
these records in memory. Admission
verifies the original path beneath its recorded bind root and compares the
verified digest with that issuance record. Audit inputs retain their invocation
cwd root; standalone binding retains cwd containment and creates no recipe record.

Records live in the server process, survive same-context execution reinstalls,
and are retained for its lifetime, including obsolete executions. Fresh contexts,
including fleet-side contexts, require their own successful recipe bind.
This boundary trusts the server process, its records, and the supplied root and
its ancestors. The recorded root is a path, without a retained directory handle
or bind-time inode identity; replacing it or an ancestor can change later path
resolution. A sibling worktree does not provide OS-level isolation.

### arch-lens

Expand Down
6 changes: 5 additions & 1 deletion src/autoskillit/core/planset/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
The IL-0 plan-set domain owns deterministic regex-only requirement extraction, allocation parsing, aggregate coverage, and verification; the server owns fetching and persistence. `plan_set_coverage` is an in-process server-side aggregate inspection, not a decision made by a child skill. Unsupported Markdown is recorded as a fail-closed marker, `text_digest` covers exact raw item spans rather than normalized text, and skills never open authority artifacts. Part commands are evidence only: the authenticated authority carries the hashed parts and coverage result. Its `state` is included in the canonical payload authenticated by `authority_digest`; admission requires both a matching recomputed digest and `state == sealed`.
The IL-0 plan-set domain owns deterministic regex-only requirement extraction, allocation parsing, aggregate coverage, and verification; the server owns fetching and persistence. `plan_set_coverage` is an in-process server-side aggregate inspection, not a decision made by a child skill. Unsupported Markdown is recorded as a fail-closed marker, `text_digest` covers exact raw item spans rather than normalized text, and skills never open authority artifacts. Part commands are evidence only: the authority carries the hashed parts and coverage result. Its `state` is included in the canonical payload covered by the unkeyed integrity hash `authority_digest`; admission requires both a matching recomputed digest and `state == sealed`.

Recipe admission also requires server-held issuance provenance: the `PlanSetMaterializer` service held by `ToolContext` records each successful recipe bind's resolved root and digest by execution ID and authority path. Its default implementation is `DefaultPlanSetMaterializer`. Admission verifies the original caller path under that recorded root, then compares the verified digest with the issued digest. Standalone binds keep cwd-rooted containment and create no recipe record; audit inputs retain their invocation-cwd root.

Records remain in memory for the server process lifetime, including obsolete executions. Reinstalling an execution on the same context preserves them; fresh contexts, including fleet-side contexts, need their own successful recipe bind. This trusts the server process, its records, and the supplied root and its ancestors. The root is a path rather than a retained directory descriptor or bind-time inode identity, so replacing the root or its ancestors can change later resolution. The digest pin does not protect directory identity, and a sibling worktree does not establish OS-level isolation.
Original file line number Diff line number Diff line change
Expand Up @@ -236,10 +236,14 @@ def __call__(self, project_dir: Path) -> frozenset[str]: ...

@runtime_checkable
class PlanSetMaterializer(Protocol):
"""Server-owned binder for a content-addressed plan-set authority."""
"""Context-held plan-set binding and successful recipe-bind provenance service."""

async def bind(self, request: PlanSetBindRequest) -> PlanSetBindResult: ...

def lookup_binding(
self, execution_generation: str, authority_path: str
) -> tuple[Path, str] | None: ...


@dataclass(frozen=True, slots=True)
class QuotaPolicy:
Expand Down
3 changes: 2 additions & 1 deletion src/autoskillit/pipeline/context.py
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,8 @@ class ToolContext:
into server-owned canonical audit authority artifacts.
plan_set_materializer:
PlanSetMaterializer — binds ordered plan parts to server-owned
plan-set authority artifacts.
plan-set authority artifacts and retains successful recipe-bind
roots and digests for server-held provenance lookup.
committed_disposition_resolver:
CommittedDispositionResolver — resolves only disposition paths
backed by the durable audit-admission ledger.
Expand Down
18 changes: 17 additions & 1 deletion src/autoskillit/server/_plan_set_materializer.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

from __future__ import annotations

import os
from collections.abc import Sequence
from datetime import UTC, datetime
from pathlib import Path
Expand All @@ -21,6 +22,7 @@
IssueSnapshotRef,
PlanPartRef,
PlanSetAuthority,
PlanSetBindingMode,
PlanSetBindRequest,
PlanSetBindResult,
PlanSetRejectReason,
Expand Down Expand Up @@ -169,6 +171,13 @@ class DefaultPlanSetMaterializer:

def __init__(self, github_client: GitHubFetcher | None) -> None:
self._github_client = github_client
self._bindings: dict[tuple[str, str], tuple[Path, str]] = {}

def lookup_binding(
self, execution_generation: str, authority_path: str
) -> tuple[Path, str] | None:
"""Return successful recipe-bind provenance; standalone binds have no record."""
return self._bindings.get((execution_generation, os.path.abspath(authority_path)))

async def bind(self, request: PlanSetBindRequest) -> PlanSetBindResult:
predecessor: PlanSetAuthority | None = None
Expand Down Expand Up @@ -224,7 +233,7 @@ async def bind(self, request: PlanSetBindRequest) -> PlanSetBindResult:
parent_path = str(Path(request.parent_authority_path).resolve())
if predecessor is parent:
predecessor_path = parent_path
return await self._bind(
result = await self._bind(
request,
root,
parent,
Expand All @@ -233,6 +242,13 @@ async def bind(self, request: PlanSetBindRequest) -> PlanSetBindResult:
predecessor_path,
predecessor_digest,
)
if result.success and request.binding_mode is PlanSetBindingMode.RECIPE:
key = (
request.execution_generation,
os.path.abspath(result.plan_set_authority_path),
)
self._bindings[key] = (root, result.plan_set_authority_digest)
return result
except Exception as exc:
logger.error("plan-set binding failed", exc_info=True)
return _failure(
Expand Down
9 changes: 9 additions & 0 deletions src/autoskillit/server/_recipe_admission.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
"""Recipe execution admission failures shared by server recipe and tool code."""


class RecipeExecutionAdmissionError(RuntimeError):
"""Stable pre-launch attested-execution rejection."""

def __init__(self, code: str, message: str) -> None:
super().__init__(message)
self.code = code
80 changes: 80 additions & 0 deletions src/autoskillit/server/recipe/_plan_set_preflight.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,95 @@

from __future__ import annotations

from collections.abc import Mapping
from pathlib import Path
from typing import TYPE_CHECKING

from autoskillit.core import (
BoundScalar,
InstalledRecipeExecution,
InvocationTemplate,
PlanSetBindingMode,
PlanSetPreflightEvidence,
PlanSetPreflightRequest,
PlanSetRejectReason,
PlanSetVerification,
PreflightKind,
RecipeExecutionId,
verify_plan_set_authority,
)
from autoskillit.server._recipe_admission import RecipeExecutionAdmissionError

if TYPE_CHECKING:
from autoskillit.pipeline import ToolContext


def _resolve_plan_set_preflight(
tool_ctx: ToolContext,
installed: InstalledRecipeExecution,
bound_input_map: Mapping[str, BoundScalar],
execution_id: str,
step_name: str,
template: InvocationTemplate,
kind: PreflightKind,
) -> PlanSetPreflightEvidence | None:
"""Use recipe_execution_preflight_* for input or service failures.

Authority and verifier rejections use input_preflight_plan_set_* codes.
"""
authority_path = bound_input_map.get("plan_set_authority_path")
if authority_path in (None, ""):
return None
stage_scope = kind is PreflightKind.PLAN_SET_STAGE_OBLIGATIONS
plan_path = None if stage_scope else bound_input_map.get("plan_path")
if not isinstance(authority_path, str) or (not stage_scope and not isinstance(plan_path, str)):
raise RecipeExecutionAdmissionError(
"recipe_execution_preflight_input",
"plan-set preflight requires bound string plan_path and authority path",
)
materializer = tool_ctx.plan_set_materializer
if materializer is None or installed.plan_set_preflight_resolver is None:
raise RecipeExecutionAdmissionError(
"recipe_execution_preflight_unavailable",
"plan-set materializer or preflight resolver is unavailable",
)
binding = materializer.lookup_binding(execution_id, authority_path)
if binding is None:
raise RecipeExecutionAdmissionError(
f"input_preflight_plan_set_{PlanSetRejectReason.AUTHORITY_INVALID.value}",
"authority was not bound by this server for the current recipe execution",
)
bind_root, issued_digest = binding
verification = installed.plan_set_preflight_resolver.resolve(
PlanSetPreflightRequest(
execution_generation=execution_id,
expected_kitchen_id=tool_ctx.kitchen_id,
step_name=step_name,
skill_name=template.invocation.skill_name or "",
plan_path=plan_path if isinstance(plan_path, str) else None,
plan_set_authority_path=authority_path,
allow_part_drift=stage_scope,
),
allowed_root=bind_root,
)
if not verification.accepted:
reason = verification.reason.value if verification.reason else "rejected"
raise RecipeExecutionAdmissionError(
f"input_preflight_plan_set_{reason}",
"; ".join(verification.detail),
)
evidence = verification.evidence
if evidence is None:
raise RecipeExecutionAdmissionError(
"recipe_execution_preflight_unavailable",
"accepted plan-set verification did not provide evidence",
)
if evidence.plan_set_authority_digest != issued_digest:
raise RecipeExecutionAdmissionError(
"input_preflight_plan_set_authority_digest",
"verified authority digest differs from its server-issued binding",
)
return evidence


class DefaultPlanSetPreflightResolver:
Expand Down
62 changes: 4 additions & 58 deletions src/autoskillit/server/recipe/_recipe_execution.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@
InventoryAdmissionDecision,
InvocationTemplate,
PlanSetPreflightEvidence,
PlanSetPreflightRequest,
PreflightEvidence,
PreflightKind,
RecipeBindingProjection,
Expand Down Expand Up @@ -55,6 +54,10 @@
compute_skill_contract_identity,
)
from autoskillit.server._misc import clear_run_skill_state
from autoskillit.server._recipe_admission import RecipeExecutionAdmissionError
from autoskillit.server.recipe._plan_set_preflight import (
_resolve_plan_set_preflight,
)

if TYPE_CHECKING:
from autoskillit.core import (
Expand All @@ -69,7 +72,6 @@

__all__ = [
"DefaultInputPreflightResolver",
"RecipeExecutionAdmissionError",
"bind_attested_runtime_invocation",
"build_bound_child_prompt",
"build_recipe_execution_snapshot",
Expand All @@ -86,14 +88,6 @@
]


class RecipeExecutionAdmissionError(RuntimeError):
"""Stable pre-launch attested-execution rejection."""

def __init__(self, code: str, message: str) -> None:
super().__init__(message)
self.code = code


class DefaultInputPreflightResolver:
"""Verify audit-cycle input provenance before any child construction."""

Expand Down Expand Up @@ -591,53 +585,6 @@ def _resolve_audit_preflight(
return audit


def _resolve_plan_set_preflight(
tool_ctx: ToolContext,
installed: InstalledRecipeExecution,
bound_input_map: Mapping[str, BoundScalar],
execution_id: str,
step_name: str,
template: InvocationTemplate,
allowed_root: Path | None,
kind: PreflightKind,
) -> PlanSetPreflightEvidence | None:
authority_path = bound_input_map.get("plan_set_authority_path")
if authority_path in (None, ""):
return None
stage_scope = kind is PreflightKind.PLAN_SET_STAGE_OBLIGATIONS
plan_path = None if stage_scope else bound_input_map.get("plan_path")
if not isinstance(authority_path, str) or (not stage_scope and not isinstance(plan_path, str)):
raise _build_preflight_input_error(
"plan-set preflight requires bound string plan_path and authority path",
)
if allowed_root is None:
raise _build_preflight_input_error("plan-set preflight requires an allowed root")
if installed.plan_set_preflight_resolver is None:
raise RecipeExecutionAdmissionError(
"recipe_execution_preflight_unavailable",
"plan-set preflight resolver is unavailable",
)
verification = installed.plan_set_preflight_resolver.resolve(
PlanSetPreflightRequest(
execution_generation=execution_id,
expected_kitchen_id=tool_ctx.kitchen_id,
step_name=step_name,
skill_name=template.invocation.skill_name or "",
plan_path=plan_path if isinstance(plan_path, str) else None,
plan_set_authority_path=authority_path,
allow_part_drift=stage_scope,
),
allowed_root=allowed_root,
)
if not verification.accepted:
reason = verification.reason.value if verification.reason else "rejected"
raise RecipeExecutionAdmissionError(
f"input_preflight_plan_set_{reason}",
"; ".join(verification.detail),
)
return verification.evidence


def resolve_attested_input_preflight(
tool_ctx: ToolContext,
installed: InstalledRecipeExecution,
Expand Down Expand Up @@ -674,7 +621,6 @@ def resolve_attested_input_preflight(
execution_id,
step_name,
template,
allowed_root,
PreflightKind(preflight_name),
)
else:
Expand Down
2 changes: 1 addition & 1 deletion src/autoskillit/server/recipe/_recipe_initialization.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@
record_initialization_page,
start_recipe_initialization,
)
from autoskillit.server._recipe_admission import RecipeExecutionAdmissionError
from autoskillit.server.lifecycle._state import _get_ctx_or_none
from autoskillit.server.recipe._recipe_execution import (
RecipeExecutionAdmissionError,
install_recipe_execution,
prepare_recipe_execution,
ready_recipe_execution_state,
Expand Down
Loading
Loading