bbagents 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
bbagents/execution.py ADDED
@@ -0,0 +1,216 @@
1
+ """Bounded async execution; adapters must cooperate with task cancellation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from dataclasses import dataclass
7
+ import math
8
+ import time
9
+ from typing import Any, Awaitable, Callable, Mapping, Protocol
10
+
11
+ from .runtime import (
12
+ Action,
13
+ ActionPolicy,
14
+ ActionResult,
15
+ ActionStatus,
16
+ AllowAllPolicy,
17
+ FailureKind,
18
+ _evaluate_policy,
19
+ )
20
+ from .hooks import HookBoundary, HookContext, HookRejected, HookRunner
21
+
22
+
23
+ @dataclass(frozen=True, slots=True)
24
+ class ExecutionContext:
25
+ deadline: float
26
+
27
+ @property
28
+ def remaining_seconds(self) -> float:
29
+ return max(0.0, self.deadline - time.monotonic())
30
+
31
+ def check_deadline(self) -> None:
32
+ if self.remaining_seconds <= 0:
33
+ raise TimeoutError("execution deadline expired")
34
+
35
+
36
+ class ExecutionAdapter(Protocol):
37
+ async def execute(self, action: Action, context: ExecutionContext) -> Any: ...
38
+
39
+
40
+ class ExecutionFailure(Exception):
41
+ def __init__(
42
+ self, message: str, kind: FailureKind, *, outcome_unknown: bool = False
43
+ ) -> None:
44
+ super().__init__(message)
45
+ self.kind = kind
46
+ self.outcome_unknown = outcome_unknown
47
+
48
+
49
+ class RetryPolicy(Protocol):
50
+ def should_retry(self, action: Action, result: ActionResult) -> bool: ...
51
+
52
+
53
+ @dataclass(frozen=True, slots=True)
54
+ class SafeRetryPolicy:
55
+ max_attempts: int = 1
56
+
57
+ def __post_init__(self) -> None:
58
+ if self.max_attempts < 1:
59
+ raise ValueError("max_attempts must be positive")
60
+
61
+ def should_retry(self, action: Action, result: ActionResult) -> bool:
62
+ return (
63
+ action.retry_safe
64
+ and not result.outcome_unknown
65
+ and result.failure_kind == FailureKind.TRANSIENT
66
+ and result.attempts < self.max_attempts
67
+ )
68
+
69
+
70
+ AsyncHandler = Callable[[Action, ExecutionContext], Awaitable[Any]]
71
+
72
+
73
+ class AsyncFunctionAdapter:
74
+ """Handlers must not block the event loop or suppress cancellation."""
75
+
76
+ def __init__(self, handlers: Mapping[str, AsyncHandler]) -> None:
77
+ self.handlers = dict(handlers)
78
+
79
+ async def execute(self, action: Action, context: ExecutionContext) -> Any:
80
+ if action.name not in self.handlers:
81
+ raise ExecutionFailure("Unknown action", FailureKind.VALIDATION)
82
+ return await self.handlers[action.name](action, context)
83
+
84
+
85
+ class SubprocessAdapter:
86
+ """Run application-allowlisted commands without a shell; kill/reap on cancel.
87
+
88
+ This is process control, not an OS security sandbox. Commands must bound their
89
+ output and manage descendants; external side effects can survive termination.
90
+ """
91
+
92
+ def __init__(self, commands: Mapping[str, tuple[str, ...]]) -> None:
93
+ self.commands = dict(commands)
94
+
95
+ async def execute(self, action: Action, context: ExecutionContext) -> str:
96
+ if action.name not in self.commands or action.parameters:
97
+ raise ExecutionFailure("Command not allowlisted", FailureKind.VALIDATION)
98
+ context.check_deadline()
99
+ process = await asyncio.create_subprocess_exec(
100
+ *self.commands[action.name],
101
+ stdout=asyncio.subprocess.PIPE,
102
+ stderr=asyncio.subprocess.PIPE,
103
+ )
104
+ try:
105
+ stdout, stderr = await process.communicate()
106
+ except BaseException:
107
+ if process.returncode is None:
108
+ process.kill()
109
+ await process.wait()
110
+ raise
111
+ if process.returncode:
112
+ raise ExecutionFailure(
113
+ stderr.decode(errors="replace"),
114
+ FailureKind.PERMANENT,
115
+ outcome_unknown=True,
116
+ )
117
+ return stdout.decode(errors="replace")
118
+
119
+
120
+ class AsyncActionRuntime:
121
+ def __init__(
122
+ self,
123
+ adapter: ExecutionAdapter,
124
+ *,
125
+ policy: ActionPolicy | None = None,
126
+ retry_policy: RetryPolicy | None = None,
127
+ hooks: HookRunner | None = None,
128
+ ) -> None:
129
+ self.adapter = adapter
130
+ self.policy = policy or AllowAllPolicy()
131
+ self.retry_policy = retry_policy or SafeRetryPolicy()
132
+ self.hooks = hooks or HookRunner()
133
+
134
+ async def execute(self, action: Action) -> ActionResult:
135
+ if not math.isfinite(action.timeout_seconds) or action.timeout_seconds <= 0:
136
+ raise ValueError("timeout_seconds must be finite and positive")
137
+ started = time.monotonic()
138
+ context = ExecutionContext(started + action.timeout_seconds)
139
+ attempt = 0
140
+ while True:
141
+ decision = _evaluate_policy(self.policy, action)
142
+ if not decision.allowed:
143
+ return ActionResult(
144
+ ActionStatus.PENDING_INTERVENTION
145
+ if decision.pending
146
+ else ActionStatus.DENIED,
147
+ error=decision.reason,
148
+ attempts=attempt,
149
+ intervention_request_id=decision.intervention_request_id,
150
+ )
151
+ attempt += 1
152
+ dispatched = False
153
+ try:
154
+ async with asyncio.timeout(context.remaining_seconds):
155
+ context.check_deadline()
156
+ await self.hooks.run(
157
+ HookContext(HookBoundary.BEFORE_ACTION, {"action": action})
158
+ )
159
+ dispatched = True
160
+ output = await self.adapter.execute(action, context)
161
+ context.check_deadline()
162
+ await self.hooks.run(
163
+ HookContext(
164
+ HookBoundary.AFTER_RESULT,
165
+ {"action": action, "output": output},
166
+ )
167
+ )
168
+ return ActionResult(
169
+ ActionStatus.SUCCEEDED,
170
+ output,
171
+ attempts=attempt,
172
+ duration_seconds=time.monotonic() - started,
173
+ )
174
+ except HookRejected as exc:
175
+ result = ActionResult(
176
+ ActionStatus.FAILED if dispatched else ActionStatus.DENIED,
177
+ error=str(exc),
178
+ attempts=attempt,
179
+ failure_kind=FailureKind.UNKNOWN
180
+ if dispatched
181
+ else FailureKind.VALIDATION,
182
+ outcome_unknown=dispatched,
183
+ )
184
+ except TimeoutError as exc:
185
+ result = ActionResult(
186
+ ActionStatus.TIMED_OUT,
187
+ error=str(exc) or "Deadline exceeded",
188
+ attempts=attempt,
189
+ failure_kind=FailureKind.TIMEOUT,
190
+ outcome_unknown=True,
191
+ )
192
+ except ExecutionFailure as exc:
193
+ result = ActionResult(
194
+ ActionStatus.FAILED,
195
+ error=str(exc),
196
+ attempts=attempt,
197
+ failure_kind=exc.kind,
198
+ outcome_unknown=exc.outcome_unknown,
199
+ )
200
+ except Exception as exc:
201
+ result = ActionResult(
202
+ ActionStatus.FAILED,
203
+ error=str(exc),
204
+ attempts=attempt,
205
+ failure_kind=FailureKind.UNKNOWN,
206
+ outcome_unknown=True,
207
+ )
208
+ result = _duration(result, time.monotonic() - started)
209
+ if not self.retry_policy.should_retry(action, result):
210
+ return result
211
+
212
+
213
+ def _duration(result: ActionResult, seconds: float) -> ActionResult:
214
+ from dataclasses import replace
215
+
216
+ return replace(result, duration_seconds=seconds)
@@ -0,0 +1,172 @@
1
+ """Reference dataset trials with application-owned isolated environments."""
2
+
3
+ from dataclasses import dataclass
4
+ import hashlib
5
+ import json
6
+ import math
7
+ from statistics import mean, pstdev
8
+ from typing import Any, Callable, ContextManager, Generic, Mapping, Sequence, TypeVar
9
+ from uuid import uuid4
10
+
11
+ from .evaluation import (
12
+ Grade,
13
+ Grader,
14
+ TrialEvidence,
15
+ TrialGrades,
16
+ TrialReport,
17
+ grade_trial,
18
+ report_trials,
19
+ )
20
+
21
+ InputT = TypeVar("InputT")
22
+ EnvironmentT = TypeVar("EnvironmentT")
23
+ OutcomeT = TypeVar("OutcomeT")
24
+
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class EvaluationCase(Generic[InputT]):
28
+ id: str
29
+ input: InputT
30
+ split: str = "regression"
31
+
32
+
33
+ @dataclass(frozen=True, slots=True)
34
+ class Dataset(Generic[InputT]):
35
+ id: str
36
+ version: str
37
+ cases: tuple[EvaluationCase[InputT], ...]
38
+
39
+ def __post_init__(self) -> None:
40
+ if (
41
+ not self.id
42
+ or not self.version
43
+ or len({case.id for case in self.cases}) != len(self.cases)
44
+ ):
45
+ raise ValueError("Datasets require identity, version and unique cases")
46
+
47
+
48
+ @dataclass(frozen=True, slots=True)
49
+ class ExperimentReport:
50
+ dataset_id: str
51
+ dataset_version: str
52
+ configuration_fingerprint: str
53
+ grades: tuple[TrialGrades, ...]
54
+ summary: TrialReport
55
+ mean_duration_seconds: float | None
56
+ duration_stddev_seconds: float | None
57
+ total_known_cost: float
58
+ trials_without_cost: int
59
+
60
+
61
+ def run_dataset(
62
+ dataset: Dataset[InputT],
63
+ *,
64
+ configuration: Mapping[str, Any],
65
+ environment: Callable[[EvaluationCase[InputT]], ContextManager[EnvironmentT]],
66
+ execute: Callable[
67
+ [EvaluationCase[InputT], EnvironmentT, str, Mapping[str, Any]],
68
+ TrialEvidence[OutcomeT],
69
+ ],
70
+ graders: Mapping[str, Grader[OutcomeT]],
71
+ repetitions: int = 1,
72
+ split: str = "regression",
73
+ ) -> ExperimentReport:
74
+ """Hosts must create/reset isolated state in each fixture and clean up on exit.
75
+
76
+ Failures propagate after fixture cleanup. This is a reference synchronous
77
+ evaluation loop, not an agent scheduler. Held-out cases run only when selected.
78
+ """
79
+
80
+ if repetitions < 1 or not graders:
81
+ raise ValueError("Evaluation requires positive repetitions and graders")
82
+ fingerprint = _fingerprint(configuration)
83
+ results: list[TrialGrades] = []
84
+ evidence: list[TrialEvidence[OutcomeT]] = []
85
+ experiment_id = uuid4().hex
86
+ for case in dataset.cases:
87
+ if case.split != split:
88
+ continue
89
+ for repetition in range(repetitions):
90
+ trial_id = f"{experiment_id}:{case.id}:{repetition}"
91
+ with environment(case) as isolated:
92
+ trial = execute(case, isolated, trial_id, configuration)
93
+ if trial.case_id != case.id or trial.trial_id != trial_id:
94
+ raise ValueError("Runner returned mismatched trial identity")
95
+ if _fingerprint(trial.configuration) != fingerprint:
96
+ raise ValueError("Runner returned mismatched configuration")
97
+ results.append(grade_trial(trial, graders))
98
+ evidence.append(trial)
99
+ durations = [trial.duration_seconds for trial in evidence]
100
+ return ExperimentReport(
101
+ dataset.id,
102
+ dataset.version,
103
+ fingerprint,
104
+ tuple(results),
105
+ report_trials(results),
106
+ mean(durations) if durations else None,
107
+ pstdev(durations) if durations else None,
108
+ sum(trial.cost for trial in evidence if trial.cost is not None),
109
+ sum(trial.cost is None for trial in evidence),
110
+ )
111
+
112
+
113
+ def _fingerprint(configuration: Mapping[str, Any]) -> str:
114
+ return hashlib.sha256(
115
+ json.dumps(
116
+ dict(configuration),
117
+ sort_keys=True,
118
+ allow_nan=False,
119
+ ).encode()
120
+ ).hexdigest()
121
+
122
+
123
+ def success_interval(
124
+ results: Sequence[TrialGrades],
125
+ *,
126
+ independent_trials: bool = False,
127
+ ) -> tuple[float, float] | None:
128
+ """95% Wilson interval, ONLY if caller justifies independent Bernoulli trials.
129
+
130
+ Unknown grades are not demonstrated successes. Correlated repetitions of a
131
+ task usually violate the independence assumption; default returns no interval.
132
+ """
133
+
134
+ if not independent_trials or not results:
135
+ return None
136
+ report = report_trials(results)
137
+ n = report.trials
138
+ p = report.passed / n
139
+ z = 1.959963984540054
140
+ denominator = 1 + z * z / n
141
+ center = (p + z * z / (2 * n)) / denominator
142
+ half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denominator
143
+ return max(0.0, center - half), min(1.0, center + half)
144
+
145
+
146
+ @dataclass(frozen=True, slots=True)
147
+ class CalibrationReport:
148
+ judge_version: str
149
+ rubric_version: str
150
+ compared: int
151
+ agreements: int
152
+ insufficient: int
153
+
154
+
155
+ def calibrate(
156
+ pairs: Sequence[tuple[Grade, Grade]],
157
+ *,
158
+ judge_version: str,
159
+ rubric_version: str,
160
+ ) -> CalibrationReport:
161
+ compared = [
162
+ (judge, human)
163
+ for judge, human in pairs
164
+ if judge.passed is not None and human.passed is not None
165
+ ]
166
+ return CalibrationReport(
167
+ judge_version,
168
+ rubric_version,
169
+ len(compared),
170
+ sum(judge.passed == human.passed for judge, human in compared),
171
+ len(pairs) - len(compared),
172
+ )
@@ -0,0 +1,85 @@
1
+ """Scoped memory with revision history and authorization before ranking."""
2
+
3
+ from dataclasses import asdict, replace
4
+ from datetime import datetime
5
+ from typing import Any, Callable
6
+
7
+ from .memory import Embedder, MemoryKind, MemoryRecord, MemoryResult, MemoryStore
8
+ from .provenance import Provenance, TrustLevel
9
+ from .revisions import RevisionRepository
10
+
11
+
12
+ class ScopedMemoryStore:
13
+ def __init__(
14
+ self,
15
+ revisions: RevisionRepository[dict[str, Any]],
16
+ *,
17
+ embed: Embedder | None = None,
18
+ ) -> None:
19
+ self.revisions = revisions
20
+ self.embed = embed
21
+
22
+ def get(self, record_id: str) -> MemoryRecord | None:
23
+ revision = self.revisions.current(record_id)
24
+ return None if revision is None else _decode(revision.value, revision.number)
25
+
26
+ def remember(
27
+ self, record: MemoryRecord, *, expected_version: int | None = None
28
+ ) -> MemoryRecord:
29
+ history = self.revisions.history(record.id)
30
+ revision = self.revisions.append(
31
+ record.id,
32
+ _encode(record),
33
+ expected_revision=len(history)
34
+ if expected_version is None
35
+ else expected_version,
36
+ reason="memory update",
37
+ activate=True,
38
+ )
39
+ return replace(record, version=revision.number)
40
+
41
+ def retrieve(
42
+ self, query: str, *, limit: int = 10, kind: MemoryKind | None = None
43
+ ) -> list[MemoryResult]:
44
+ # Authorization and scope selection happen before embeddings or scoring.
45
+ items = self.revisions.items()
46
+ memory = MemoryStore(self.embed)
47
+ versions: dict[str, int] = {}
48
+ for item_id, revision in items:
49
+ memory.remember(_decode(revision.value, revision.number))
50
+ versions[item_id] = revision.number
51
+ return [
52
+ MemoryResult(
53
+ replace(result.record, version=versions[result.record.id]), result.score
54
+ )
55
+ for result in memory.retrieve(query, limit=limit, kind=kind)
56
+ ]
57
+
58
+ def forget(self, predicate: Callable[[MemoryRecord], bool]) -> int:
59
+ removed = 0
60
+ for item_id, revision in self.revisions.items():
61
+ if predicate(_decode(revision.value, revision.number)):
62
+ self.revisions.activate(
63
+ item_id, None, expected_active=revision.number, reason="archived"
64
+ )
65
+ removed += 1
66
+ return removed
67
+
68
+
69
+ def _encode(record: MemoryRecord) -> dict[str, Any]:
70
+ data = asdict(record)
71
+ data["created_at"] = record.created_at.isoformat()
72
+ data["provenance"]["received_at"] = record.provenance.received_at.isoformat()
73
+ return data
74
+
75
+
76
+ def _decode(data: dict[str, Any], version: int) -> MemoryRecord:
77
+ values = dict(data)
78
+ values["kind"] = MemoryKind(values["kind"])
79
+ values["created_at"] = datetime.fromisoformat(values["created_at"])
80
+ provenance = dict(values["provenance"])
81
+ provenance["trust"] = TrustLevel(provenance["trust"])
82
+ provenance["received_at"] = datetime.fromisoformat(provenance["received_at"])
83
+ values["provenance"] = Provenance(**provenance)
84
+ values["version"] = version
85
+ return MemoryRecord(**values)
bbagents/hooks.py ADDED
@@ -0,0 +1,78 @@
1
+ """Bounded, traced async enforcement boundaries with explicit failure behavior."""
2
+
3
+ import asyncio
4
+ from dataclasses import dataclass, field
5
+ from enum import Enum
6
+ import math
7
+ from typing import Any, Awaitable, Callable, Mapping
8
+
9
+ from .core import NullTrace, TraceSink
10
+
11
+
12
+ class HookBoundary(str, Enum):
13
+ BEFORE_MODEL = "before_model"
14
+ BEFORE_ACTION = "before_action"
15
+ AFTER_RESULT = "after_result"
16
+ BEFORE_COMPLETE = "before_complete"
17
+
18
+
19
+ @dataclass(frozen=True, slots=True)
20
+ class HookContext:
21
+ boundary: HookBoundary
22
+ values: Mapping[str, Any] = field(default_factory=dict)
23
+
24
+
25
+ @dataclass(frozen=True, slots=True)
26
+ class HookDecision:
27
+ allowed: bool
28
+ reason: str = ""
29
+
30
+
31
+ @dataclass(frozen=True, slots=True)
32
+ class Hook:
33
+ name: str
34
+ boundary: HookBoundary
35
+ callback: Callable[[HookContext], Awaitable[HookDecision]]
36
+ timeout_seconds: float = 5.0
37
+ blocking: bool = True
38
+
39
+ def __post_init__(self) -> None:
40
+ if not math.isfinite(self.timeout_seconds) or self.timeout_seconds <= 0:
41
+ raise ValueError("hook timeout must be finite and positive")
42
+ if not self.blocking and self.boundary != HookBoundary.AFTER_RESULT:
43
+ raise ValueError("Only observational AFTER_RESULT hooks may fail open")
44
+
45
+
46
+ class HookRejected(RuntimeError):
47
+ pass
48
+
49
+
50
+ class HookRunner:
51
+ """Callbacks must cooperate with cancellation; hooks confer no capabilities."""
52
+
53
+ def __init__(
54
+ self, hooks: tuple[Hook, ...] = (), *, trace: TraceSink | None = None
55
+ ) -> None:
56
+ self.hooks = hooks
57
+ self.trace = trace or NullTrace()
58
+
59
+ async def run(self, context: HookContext) -> None:
60
+ for hook in self.hooks:
61
+ if hook.boundary != context.boundary:
62
+ continue
63
+ self.trace.record(
64
+ "hook.started", {"hook": hook.name, "boundary": context.boundary.value}
65
+ )
66
+ try:
67
+ async with asyncio.timeout(hook.timeout_seconds):
68
+ decision = await hook.callback(context)
69
+ except Exception as exc:
70
+ self.trace.record("hook.failed", {"hook": hook.name, "error": str(exc)})
71
+ if hook.blocking:
72
+ raise HookRejected(f"Hook {hook.name} failed") from exc
73
+ continue
74
+ self.trace.record(
75
+ "hook.finished", {"hook": hook.name, "allowed": decision.allowed}
76
+ )
77
+ if not decision.allowed:
78
+ raise HookRejected(f"Hook {hook.name}: {decision.reason}")
@@ -0,0 +1 @@
1
+ """Optional adapters for external orchestration and integration runtimes."""
@@ -0,0 +1,101 @@
1
+ """Optional reviewed-manifest Agent Skills loader; never executes bundled code."""
2
+
3
+ from dataclasses import dataclass, field
4
+ import hashlib
5
+ from importlib import import_module
6
+ from pathlib import Path
7
+ from typing import Mapping
8
+
9
+ from ..revisions import AccessContext, AccessPolicy
10
+ from ..skills import Skill, SkillDescriptor
11
+
12
+
13
+ @dataclass(frozen=True, slots=True)
14
+ class PinnedSkill:
15
+ """Trusted deployment manifest, kept outside the agent-writable workspace."""
16
+
17
+ descriptor: SkillDescriptor
18
+ directory: str
19
+ sha256: str
20
+ resources: Mapping[str, str] = field(default_factory=dict)
21
+
22
+
23
+ class FilesystemSkillSource:
24
+ def __init__(
25
+ self,
26
+ root: Path,
27
+ pins: tuple[PinnedSkill, ...],
28
+ context: AccessContext,
29
+ policy: AccessPolicy,
30
+ *,
31
+ max_bytes: int = 1_000_000,
32
+ ) -> None:
33
+ self.root = root.resolve()
34
+ self.context = context
35
+ self.policy = policy
36
+ self.max_bytes = max_bytes
37
+ self.pins = {(pin.descriptor.id, pin.descriptor.version): pin for pin in pins}
38
+ if len(self.pins) != len(pins):
39
+ raise ValueError("Duplicate skill revision")
40
+
41
+ def _authorize(self, operation: str) -> None:
42
+ if not self.policy.permits(self.context, operation):
43
+ raise PermissionError(f"Skill access denied: {operation}")
44
+
45
+ def discover(self, *, scope: str) -> tuple[SkillDescriptor, ...]:
46
+ self._authorize("skill.discover")
47
+ if scope != self.context.scope:
48
+ raise PermissionError("Skill scope mismatch")
49
+ return tuple(
50
+ pin.descriptor
51
+ for pin in self.pins.values()
52
+ if pin.descriptor.scope == scope
53
+ )
54
+
55
+ def _pin(self, skill_id: str, version: str) -> PinnedSkill:
56
+ pin = self.pins[(skill_id, version)]
57
+ if pin.descriptor.scope != self.context.scope:
58
+ raise PermissionError("Skill scope mismatch")
59
+ return pin
60
+
61
+ def _read(self, pin: PinnedSkill, relative: str, digest: str) -> bytes:
62
+ directory = (self.root / pin.directory).resolve()
63
+ path = (directory / relative).resolve()
64
+ if not directory.is_relative_to(self.root) or not path.is_relative_to(
65
+ directory
66
+ ):
67
+ raise PermissionError("Skill path escapes its reviewed directory")
68
+ with path.open("rb") as handle:
69
+ data = handle.read(self.max_bytes + 1)
70
+ if len(data) > self.max_bytes:
71
+ raise ValueError("Skill resource exceeds size limit")
72
+ if hashlib.sha256(data).hexdigest() != digest:
73
+ raise ValueError("Skill revision digest changed")
74
+ return data
75
+
76
+ def load(self, skill_id: str, *, version: str) -> Skill:
77
+ self._authorize("skill.load")
78
+ pin = self._pin(skill_id, version)
79
+ text = (
80
+ self._read(pin, "SKILL.md", pin.sha256)
81
+ .decode("utf-8")
82
+ .replace("\r\n", "\n")
83
+ )
84
+ if not text.startswith("---\n") or "\n---\n" not in text[4:]:
85
+ raise ValueError("SKILL.md requires YAML frontmatter")
86
+ header, instructions = text[4:].split("\n---\n", 1)
87
+ try:
88
+ yaml = import_module("yaml")
89
+ except ModuleNotFoundError as exc:
90
+ raise RuntimeError("Install bbagents[skills] to parse SKILL.md") from exc
91
+ metadata = yaml.safe_load(header)
92
+ if not isinstance(metadata, dict) or metadata.get("name") != skill_id:
93
+ raise ValueError("Skill name does not match manifest")
94
+ if metadata.get("description") != pin.descriptor.description:
95
+ raise ValueError("Skill description does not match manifest")
96
+ return Skill(pin.descriptor, instructions, tuple(pin.resources))
97
+
98
+ def read_resource(self, skill_id: str, *, version: str, resource: str) -> bytes:
99
+ self._authorize("skill.resource")
100
+ pin = self._pin(skill_id, version)
101
+ return self._read(pin, resource, pin.resources[resource])