stacktrace-cli 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
 # logged in any other process would reach Python's last-resort handler and

stacktrace_cli/cloud/setup.sh

@@ -38,8 +38,8 @@
 # home, because that home does not exist until this run creates it.
 #
 # Options (all optional):
-#   --asset-id VALUE   use this asset id instead of minting one; also taken
-#                      from STACKTRACE_ASSET_EXTERNAL_ID in the environment
+#   --asset-id VALUE   use this asset id instead of minting a bare UUID; also
+#                      taken from STACKTRACE_ASSET_EXTERNAL_ID in the environment
 #   --root DIR         treat DIR as / (for testing)
 #
 # The remote token and API URL, and the Slack webhook URL, are read by the boot
@@ -82,7 +82,9 @@ _uuid() {
 }
 
 DISPLAY_PREFIX="cloud"
-[ -n "$ASSET_ID" ] || ASSET_ID="cloud-$(_uuid)"
+# A bare UUID, like every key `remote/identity.py` mints (ADR-0105). The kind of
+# box is the label's business (asset-display-prefix below), not the key's.
+[ -n "$ASSET_ID" ] || ASSET_ID="$(_uuid)"
 # remote/identity.py:_is_identifier rejects whitespace, non-printable
 # characters, and anything over 255 characters. A value this accepts but the
 # runtime rejects is worse than no file: every session reads it, rejects it,

stacktrace_cli/correlate/acquire.py

@@ -39,6 +39,7 @@ from typing import Any
 from stacktrace_cli.correlate.composition import (
     Advisory,
     Composition,
+    composable,
     composition_from_bom,
     reject_malformed_shape,
     root_property,
@@ -234,8 +235,13 @@ def build_bom(
 
     Returns None rather than raising when nothing was produced: a machine can run
     one agent kind and not another, which is a fact about the machine rather than
-    a failure to look.
+    a failure to look. A kind OpenACA does not know is the same answer for the
+    same reason -- sessions can come from an agent whose setup OpenACA cannot
+    describe yet, and those sessions resolve as having no composition rather than
+    failing every other kind's run.
     """
+    if not composable(agent_kind):
+        return None
     with tempfile.TemporaryDirectory() as scratch:
         directory = Path(scratch)
         argv = [

stacktrace_cli/correlate/composition.py

@@ -24,11 +24,25 @@ so a legitimate flat BOM resolves instead of being rejected.
 
 from __future__ import annotations
 
+import json
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any
 
-from openaca.core import bom_components_from_cyclonedx
+from openaca.core import KindSelectionError, bom_components_from_cyclonedx, validate_kind_selection
+
+
+def composable(agent_kind: str) -> bool:
+    """Whether OpenACA can describe this agent kind's setup at all.
+
+    Asked through the facade's own check rather than a list of ours, so a kind
+    OpenACA learns reaches this package with the pin and no change here.
+    """
+    try:
+        validate_kind_selection(agent_kind, None)
+    except KindSelectionError:
+        return False
+    return True
 
 
 @dataclass(frozen=True)
@@ -126,6 +140,12 @@ class Composition:
     #: one agent as two rows. Defaulted rather than positional so it sits with
     #: the fields a document may omit, though it belongs beside `agent_kind`.
     agent_instance_id: str | None = None
+    #: The sub-agent types and skills the agent provides itself, as OpenACA
+    #: lists them on the BOM root (its ADR-0076). Never components: nothing
+    #: installed them, so `find` never answers with one. Empty for a BOM that
+    #: lists none, which is every BOM OpenACA wrote before it listed them.
+    builtin_agents: frozenset[str] = frozenset()
+    builtin_skills: frozenset[str] = frozenset()
 
     def find(self, component_type: str, name: str) -> tuple[Component, ...]:
         """Every component of this type and name, in BOM order.
@@ -181,6 +201,8 @@ def composition_from_bom(
         advisories=advisories or {},
         advisories_checked=advisories is not None,
         agent_instance_id=_declared_instance_id(document),
+        builtin_agents=_declared_builtins(document, _BUILTIN_AGENTS_PROPERTY),
+        builtin_skills=_declared_builtins(document, _BUILTIN_SKILLS_PROPERTY),
     )
 
 
@@ -211,6 +233,29 @@ def _declared_instance_id(document: dict[str, Any]) -> str | None:
     return declared if declared and declared.strip() else None
 
 
+_BUILTIN_AGENTS_PROPERTY = "openaca:builtin_agents"
+_BUILTIN_SKILLS_PROPERTY = "openaca:builtin_skills"
+
+
+def _declared_builtins(document: dict[str, Any], name: str) -> frozenset[str]:
+    """A JSON array of names on the root, or nothing.
+
+    A malformed list reads as none, as a blank `openaca:agent_id` does: each
+    built-in call then reads as absent, which is visible, while rejecting the
+    document would lose every other call's answer with it.
+    """
+    declared = root_property(document, name)
+    if declared is None:
+        return frozenset()
+    try:
+        names = json.loads(declared)
+    except json.JSONDecodeError:
+        return frozenset()
+    if not isinstance(names, list) or not all(isinstance(n, str) and n for n in names):
+        return frozenset()
+    return frozenset(names)
+
+
 def root_property(document: dict[str, Any], name: str) -> str | None:
     """One `metadata.component` property's value, or `None`.
 

stacktrace_cli/correlate/join.py

@@ -13,7 +13,7 @@ would invent the evidence a later stage would then act on.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal
+from typing import Literal, Protocol
 
 from stacktrace_cli.correlate.composition import Component, Composition
 from stacktrace_cli.sessions.protocols import ToolCallLike
@@ -58,118 +58,24 @@ unresolvable by construction rather than by omission. Collapsing them reads as
 """
 EdgeType = Literal["observed_invocation"]
 
-#: Built-in tool names per agent kind. The agent itself is the actor for these,
-#: so they resolve to the agent root rather than to any component.
-#:
-#: Closed and per-kind on purpose: a kind with no known set returns False for
-#: every name, so a new kind starts honestly unresolved rather than silently
-#: promoted. The cost of the closed list is that it drifts as an agent adds
-#: tools — measured over 200 sessions, an earlier ten-name list left 489 calls
-#: reading `unresolved` when the agent itself had plainly made them, which is a
-#: worse answer than saying so. Every name below was observed in a real
-#: transcript; a name that stops appearing is left in place, since an old
-#: session still names it.
-_BUILTIN_TOOLS: dict[str, frozenset[str]] = {
-    "claude-code": frozenset(
-        {
-            # File and shell
-            "Read",
-            "Write",
-            "Edit",
-            "Bash",
-            "Glob",
-            "Grep",
-            "NotebookEdit",
-            # Retrieval
-            "WebFetch",
-            "WebSearch",
-            "ToolSearch",
-            # Session and planning surface
-            "TodoWrite",
-            "ExitPlanMode",
-            "EnterPlanMode",
-            "AskUserQuestion",
-            "Artifact",
-            "ReportFindings",
-            # Background work and messaging
-            "Monitor",
-            "TaskOutput",
-            "TaskStop",
-            "SendMessage",
-            "SendUserFile",
-            "ListAgents",
-        }
-    )
-}
-
-#: Subagent types an agent kind provides itself. `Agent` naming one of these is
-#: the agent dispatching its own generic worker, not an installed component, so
-#: it resolves to the agent root exactly as a built-in tool does. A name outside
-#: this set is a configured subagent and joins to an `agent` component.
-_BUILTIN_SUBAGENTS: dict[str, frozenset[str]] = {
-    "claude-code": frozenset(
-        {
-            "general-purpose",
-            "Explore",
-            "Plan",
-            "claude",
-            # Shipped inside the executable rather than installed, so no scan of
-            # the filesystem can see them; see `_BUILTIN_SKILLS`.
-            "claude-code-guide",
-            "statusline-setup",
-            "output-style-setup",
-        }
-    )
-}
-
-#: Skills an agent kind ships *inside its own executable*. Not a scanning gap:
-#: these have no manifest, no directory and no package anywhere on the
-#: filesystem, so no composition analysis can find them however thorough it is.
-#: Extracted from the shipped binary rather than guessed — every name below
-#: appears there as skill frontmatter.
-#:
-#: Unlike built-in tools, these are consulted only *after* the composition has
-#: been asked and has no answer. The names are ordinary words — `plan`, `run`,
-#: `design`, `verify` — that a user's own skill may legitimately take, and
-#: checking them first would attribute an installed skill's call to the agent
-#: itself. Installed always wins; this is the fallback.
-_BUILTIN_SKILLS: dict[str, frozenset[str]] = {
-    "claude-code": frozenset(
-        {
-            "api-design",
-            "artifact-components",
-            "artifact-dashboard",
-            "artifact-data-table",
-            "artifact-design",
-            "artifact-diagramming",
-            "artifact-explainer",
-            "artifact-pr-review",
-            "artifact-report",
-            "code-reviewer",
-            "coding-standards",
-            "design",
-            "design-sync",
-            "doc",
-            "example",
-            "fix-lint",
-            "import-to-claude-code",
-            "meeting-notes",
-            "plan",
-            "plan-artifact",
-            "prototype",
-            "review-changes",
-            "run",
-            "run-skill-generator",
-            "sheet",
-            "slides",
-            "ticket-analyzer",
-            "verify",
-            "whiteboard",
-            "workshop",
-            "workshop-page",
-        }
-    )
-}
+#: Tool classes whose calls the agent itself makes. OpenAIDR classes every call
+#: per kind (its ADR-0021), so this is the whole of "built-in" for any kind it
+#: reads: a call it could not class is `None` and stays unrecognized, never
+#: silently promoted. `delegate` and `skill` name a component, so a call in
+#: either is resolved by what it names, and `mcp` by its server.
+_AGENT_ACTS = frozenset(
+    {
+        "shell",
+        "shell_control",
+        "file_read",
+        "file_search",
+        "file_write",
+        "file_edit",
+        "web_fetch",
+        "web_search",
+        "other",
+    }
+)
 
 #: Component types a composition may answer a key with, beyond the key's own.
 #:
@@ -181,12 +87,12 @@ _BUILTIN_SKILLS: dict[str, frozenset[str]] = {
 #: leaves a component that is plainly installed reading as absent.
 _EQUIVALENT_TYPES: dict[str, tuple[str, ...]] = {"skill": ("command",)}
 
-#: Tool name -> (component type, the argument naming the component). Verified
-#: against real Claude Code sessions: `Skill` carries `input.skill`, and subagent
-#: dispatch is `Agent` with `input.subagent_type`.
+#: Tool class -> (component type, the canonical argument naming it). A call
+#: that runs a skill names it under `skill`, and one that dispatches a subagent
+#: names it under `agent`, whatever the kind records them as.
 _ARGUMENT_SIGNALS: dict[str, tuple[str, str]] = {
-    "Skill": ("skill", "skill"),
-    "Agent": ("agent", "subagent_type"),
+    "skill": ("skill", "skill"),
+    "delegate": ("agent", "agent"),
 }
 
 
@@ -220,25 +126,68 @@ class Resolution:
     target: str | None
 
 
-def is_builtin(tool_name: str, agent_kind: str) -> bool:
-    """Whether this kind's own agent is the actor for this tool."""
-    return tool_name in _BUILTIN_TOOLS.get(agent_kind, frozenset())
+class NamedTool(Protocol):
+    """What deciding a built-in reads: a call, or a summary of one."""
 
+    @property
+    def tool_name(self) -> str: ...
+    @property
+    def mcp_server(self) -> str | None: ...
+    @property
+    def tool_class(self) -> str | None: ...
 
-def is_builtin_subagent(call: ToolCallLike, agent_kind: str) -> bool:
-    """Whether this call dispatches a subagent the agent kind provides itself."""
-    if call.tool_name != "Agent":
+
+def is_builtin(call: NamedTool, agent_kind: str) -> bool:
+    """Whether this kind's own agent is the actor for this call.
+
+    An MCP server picks its own tool names, and nothing stops one from choosing
+    `Read` or `Bash`; `call.mcp_server` is the client's own record of where the
+    call went, so a call carrying one is never the agent's.
+    """
+    del agent_kind  # The class is filled per kind upstream; nothing here varies by it.
+    if call.mcp_server:
         return False
-    requested = (call.arguments or {}).get("subagent_type")
-    return isinstance(requested, str) and requested in _BUILTIN_SUBAGENTS.get(
-        agent_kind, frozenset()
+    return call.tool_class in _AGENT_ACTS
+
+
+def _requested_subagent(call: ToolCallLike) -> str | None:
+    """The subagent a delegating call asked for, or None."""
+    if call.tool_class != "delegate":
+        return None
+    requested = call.canonical_arguments.get("agent")
+    return requested if isinstance(requested, str) and requested else None
+
+
+def is_builtin_subagent(call: ToolCallLike, composition: Composition | None) -> bool:
+    """Whether this call dispatches a subagent type the agent provides itself.
+
+    Naming one is the agent dispatching its own generic worker, not an
+    installed component, so it resolves to the agent root exactly as a
+    built-in tool does. Asked of the composition, which lists what its kind
+    provides (OpenACA ADR-0076): a name outside that list is a configured
+    subagent and joins to an `agent` component.
+    """
+    requested = _requested_subagent(call)
+    return (
+        requested is not None
+        and composition is not None
+        and requested in composition.builtin_agents
     )
 
 
-def is_builtin_skill(key: JoinKey, agent_kind: str) -> bool:
-    """Whether this key names a skill the agent kind ships inside its executable."""
-    return key.component_type == "skill" and key.name in _BUILTIN_SKILLS.get(
-        agent_kind, frozenset()
+def is_builtin_skill(key: JoinKey, composition: Composition | None) -> bool:
+    """Whether this key names a skill the agent ships itself.
+
+    Consulted only *after* the composition's components have no answer. The
+    names are ordinary words — `run`, `design`, `verify` — that a user's own
+    skill may legitimately take, and checking them first would attribute an
+    installed skill's call to the agent itself. Installed always wins; this is
+    the fallback.
+    """
+    return (
+        key.component_type == "skill"
+        and composition is not None
+        and key.name in composition.builtin_skills
     )
 
 
@@ -256,7 +205,9 @@ def candidates_for(key: JoinKey, composition: Composition) -> tuple[Component, .
     return candidates
 
 
-def builtin_category_and_name(call: ToolCallLike, agent_kind: str) -> tuple[str, str] | None:
+def builtin_category_and_name(
+    call: ToolCallLike, composition: Composition | None
+) -> tuple[str, str] | None:
     """What a built-in resolution was, re-asked rather than read.
 
     A built-in's `Resolution` is `key=None, candidates=(), target=root` and is
@@ -267,13 +218,12 @@ def builtin_category_and_name(call: ToolCallLike, agent_kind: str) -> tuple[str,
     attribution and a finding's own subject have to give the same answer, and
     two copies is how they would come to differ.
     """
-    if is_builtin_subagent(call, agent_kind):
-        requested = (call.arguments or {}).get("subagent_type")
-        return "subagent", str(requested)
-    if is_builtin(call.tool_name, agent_kind):
+    if is_builtin_subagent(call, composition):
+        return "subagent", str(_requested_subagent(call))
+    if is_builtin(call, composition.agent_kind if composition is not None else ""):
         return "tool", call.tool_name
     key = join_key(call)
-    if key is not None and is_builtin_skill(key, agent_kind):
+    if key is not None and is_builtin_skill(key, composition):
         return "skill", key.name
     return None
 
@@ -295,6 +245,14 @@ def join_key(call: ToolCallLike) -> JoinKey | None:
     return JoinKey(component_type, name if call.mcp_server else _unqualified(name))
 
 
+def listed_key(component_type: str, name: str) -> JoinKey:
+    """The key a component the agent's own context lists by name is looked up
+    by: as a call naming it would be (`join_key`), a skill's plugin qualifier
+    dropped and a server's name kept as the client recorded it. Ask it with
+    `candidates_for`, so a skill inventoried as a command still answers."""
+    return JoinKey(component_type, name if component_type == "mcp_server" else _unqualified(name))
+
+
 def addressed_naming(call: ToolCallLike) -> tuple[str, str] | None:
     """The component type this call named, and the word it named it by.
 
@@ -311,11 +269,11 @@ def addressed_naming(call: ToolCallLike) -> tuple[str, str] | None:
     """
     if call.mcp_server:
         return "mcp_server", call.mcp_server
-    signal = _ARGUMENT_SIGNALS.get(call.tool_name)
+    signal = _ARGUMENT_SIGNALS.get(call.tool_class or "")
     if signal is None:
         return None
     component_type, argument = signal
-    value = (call.arguments or {}).get(argument)
+    value = call.canonical_arguments.get(argument)
     if not isinstance(value, str) or not value:
         return None
     return component_type, value
@@ -342,13 +300,10 @@ def _unqualified(name: str) -> str:
 
 def resolve(call: ToolCallLike, composition: Composition) -> Resolution:
     """Resolve one call against one composition."""
-    # An MCP server picks its own tool names, and nothing stops one from
-    # choosing `Read` or `Bash`. `call.mcp_server` is the client's own record of
-    # where the call actually went, so a call carrying one is never read as a
-    # built-in: the server key, not the borrowed name, decides what this named.
+    # A call carrying a server is never read as a built-in (`is_builtin`): the
+    # server key, not a borrowed tool name, decides what it named.
     if not call.mcp_server and (
-        is_builtin(call.tool_name, composition.agent_kind)
-        or is_builtin_subagent(call, composition.agent_kind)
+        is_builtin(call, composition.agent_kind) or is_builtin_subagent(call, composition)
     ):
         # The agent is the actor. Naming a component here would attribute the
         # call to something that did not make it.
@@ -364,7 +319,7 @@ def resolve(call: ToolCallLike, composition: Composition) -> Resolution:
 
     key = join_key(call)
     if key is None:
-        recognized = bool(call.mcp_server) or call.tool_name in _ARGUMENT_SIGNALS
+        recognized = bool(call.mcp_server) or call.tool_class in _ARGUMENT_SIGNALS
         return _unresolved(
             call.span,
             None,
@@ -373,7 +328,7 @@ def resolve(call: ToolCallLike, composition: Composition) -> Resolution:
 
     candidates = candidates_for(key, composition)
     if len(candidates) == 0:
-        if is_builtin_skill(key, composition.agent_kind):
+        if is_builtin_skill(key, composition):
             # Asked after the composition, never before: an installed skill of
             # the same name is the real target, and this is only what remains.
             # `key` is dropped exactly as it is for a built-in tool: the agent

stacktrace_cli/correlate/observed.py

@@ -52,21 +52,19 @@ CAPABILITY_NAMES = frozenset(
 #: claim about intent.
 NEVER_OBSERVED = frozenset({"credential_access", "sensitive_data_access"})
 
-#: A tool whose identity *is* the capability. No interpretation: `WebFetch`
-#: reaches the network because that is what the tool is. Covers 95.6% of calls
-#: on a measured corpus — 23,835 of 24,934 — which is why every other mechanism
-#: below is a refinement rather than the mechanism.
-_TOOL_CAPABILITY: dict[str, str] = {
-    "Bash": "shell_exec",
-    "Read": "file_read",
-    "Grep": "file_read",
-    "Glob": "file_read",
-    "NotebookRead": "file_read",
-    "Write": "file_write",
-    "Edit": "file_write",
-    "NotebookEdit": "file_write",
-    "WebFetch": "network_egress",
-    "WebSearch": "network_egress",
+#: A tool whose identity *is* the capability, by the class OpenAIDR gives it
+#: for every kind. No interpretation: a web fetch reaches the network because
+#: that is what the tool is. Covers 95.6% of calls on a measured corpus --
+#: 23,835 of 24,934 -- which is why every other mechanism below is a refinement
+#: rather than the mechanism.
+_CLASS_CAPABILITY: dict[str, str] = {
+    "shell": "shell_exec",
+    "file_read": "file_read",
+    "file_search": "file_read",
+    "file_write": "file_write",
+    "file_edit": "file_write",
+    "web_fetch": "network_egress",
+    "web_search": "network_egress",
 }
 
 #: Head binaries that say more about a shell call than `shell_exec` alone.
@@ -987,15 +985,16 @@ def observe(call: ToolCallLike) -> tuple[Observation, ...]:
     # claimed by the server, is the only capability this function may report
     # for one.
     if not call.mcp_server:
-        capability = _TOOL_CAPABILITY.get(call.tool_name)
+        capability = _CLASS_CAPABILITY.get(call.tool_class or "")
         if capability:
             found[capability] = Observation(
                 capability=capability,
                 confidence="high",
                 evidence={"kind": "tool_name", "value": call.tool_name},
             )
-        if call.tool_name == "Bash":
-            for binary, arguments in command_segments((call.arguments or {}).get("command")):
+        if call.tool_class == "shell":
+            command = call.canonical_arguments.get("command")
+            for binary, arguments in command_segments(command):
                 for name, cited in _segment_capabilities(binary, arguments):
                     # `shell_exec` is already recorded at high confidence from the
                     # tool itself; a parsed binary must never downgrade it.
@@ -1016,7 +1015,7 @@ def observe(call: ToolCallLike) -> tuple[Observation, ...]:
             # Registering the redirect first would relabel those writes as
             # redirect-derived and narrow a match to a target that is not theirs.
             if "file_write" not in found:
-                for target in redirect_targets((call.arguments or {}).get("command")):
+                for target in redirect_targets(command):
                     found["file_write"] = Observation(
                         capability="file_write",
                         confidence="medium",