induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/cards/task.py

@@ -0,0 +1,256 @@
+"""Task capability — delegate a self-contained piece of work to a sub-agent.
+
+App-novel wiring. The ``task`` tool lets the primary agent hand off a bounded
+objective (e.g. "find every call site of ``foo`` and summarize them") to a
+fresh sub-agent that runs its own tool loop and reports back a single result,
+keeping the parent's context window clean.
+
+The actual sub-agent runner is NOT owned by this card — it is a framework /
+swarm concern injected through :attr:`DeckContext.framework` under the
+:data:`DELEGATE_HANDLE_KEY` key. When that handle is present the capability
+delegates to it; when it is absent (tests, headless tooling, a host that has
+not wired the swarm) the capability degrades gracefully to a clearly-typed
+stub that reports delegation is unavailable rather than throwing. Either way
+the card builds a valid :data:`Capability` and the deck assembles and runs.
+
+Port note: the TypeBox schema becomes a dict-literal JSON Schema, and a
+defensive runtime guard replaces the compile-time requirement on
+``objective``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from indusagi.agent import AgentToolResult
+from indusagi.ai import TextContent
+
+from ..contract import Capability, CapabilityCard, DeckContext, Schema, capability_id
+
+__all__ = [
+    "DELEGATE_HANDLE_KEY",
+    "DelegateRequest",
+    "DelegateResult",
+    "DelegateRunner",
+    "TaskDetails",
+    "build_task_capability",
+    "task_card",
+]
+
+
+# ---------------------------------------------------------------------------
+# Delegate handle (injected via DeckContext.framework)
+# ---------------------------------------------------------------------------
+
+#: Key under which a host wires a live delegate runner into the deck context.
+DELEGATE_HANDLE_KEY = "delegate"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DelegateRequest:
+    """A single delegated objective handed to the sub-agent runner."""
+
+    # The self-contained objective the sub-agent should accomplish.
+    objective: str
+    # Optional named agent profile to run as (e.g. "explorer", "reviewer").
+    agent: str | None = None
+    # Optional extra context the parent wants the sub-agent to start with.
+    context: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DelegateResult:
+    """The single result a sub-agent reports back to the parent."""
+
+    # Whether the sub-agent considers the objective met.
+    ok: bool
+    # The sub-agent's final report, surfaced to the parent agent verbatim.
+    report: str
+
+
+class DelegateRunner(Protocol):
+    """The contract a host's sub-agent runner must satisfy to be wired in.
+
+    Intentionally minimal: the deck only needs a way to run one objective
+    under cancellation and get one report back. How the runner spawns the
+    sub-agent (in-process loop, worktree, separate process) is entirely the
+    host's concern. A runner *may* also expose a ``list_agents()`` returning
+    the named profiles it offers; the tool description surfaces them when
+    present (read via ``getattr``, the Python stand-in for the TS optional
+    method).
+    """
+
+    def run(
+        self, request: DelegateRequest, signal: object | None = None
+    ) -> Awaitable[DelegateResult]:
+        """Run one delegated objective and resolve with the sub-agent's
+        report."""
+        ...
+
+
+def _read_delegate_runner(ctx: DeckContext) -> DelegateRunner | None:
+    handle = (ctx.framework or {}).get(DELEGATE_HANDLE_KEY)
+    if handle is not None and callable(getattr(handle, "run", None)):
+        return handle  # type: ignore[return-value] — structural check above
+    return None
+
+
+def _list_agents(runner: DelegateRunner | None) -> Sequence[str]:
+    lister = getattr(runner, "list_agents", None)
+    if callable(lister):
+        try:
+            return tuple(lister())
+        except Exception:
+            return ()
+    return ()
+
+
+# ---------------------------------------------------------------------------
+# Parameters (dict-literal JSON Schema)
+# ---------------------------------------------------------------------------
+
+_TASK_PARAMS: Schema = {
+    "type": "object",
+    "properties": {
+        "objective": {
+            "type": "string",
+            "description": (
+                "A complete, self-contained statement of what the sub-agent should "
+                "accomplish. Include everything it needs; it does not share your "
+                "conversation history."
+            ),
+        },
+        "agent": {
+            "type": "string",
+            "description": (
+                "Optional named sub-agent profile to run as. Omit to use the "
+                "default profile."
+            ),
+        },
+        "context": {
+            "type": "string",
+            "description": "Optional extra background the sub-agent should start with.",
+        },
+    },
+    "required": ["objective"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TaskDetails:
+    """Structured detail returned alongside the model-facing content."""
+
+    # True when a delegate runner handled the objective.
+    delegated: bool
+    # True when the sub-agent (or stub) considers the objective met.
+    ok: bool
+    # The agent profile that ran, if one was named.
+    agent: str | None = None
+
+
+def _base_description(agents: Sequence[str]) -> str:
+    roster = f" Available sub-agent profiles: {', '.join(agents)}." if agents else ""
+    return (
+        "Delegate a focused, self-contained piece of work to a sub-agent that runs its own "
+        "tool loop and returns a single report. Use this to keep your own context clean when a "
+        "task is well-scoped — searching a large codebase, drafting a file, or investigating a "
+        "question end-to-end. Give a complete `objective`; the sub-agent does not see your "
+        "conversation." + roster
+    )
+
+
+_STUB_NOTE = (
+    "Sub-agent delegation is not wired in this environment, so the objective was not run. "
+    "Wire a DelegateRunner into the deck context to enable it, or perform the work inline "
+    "with the other tools."
+)
+
+
+def _field(params: object, key: str) -> object:
+    if isinstance(params, Mapping):
+        return params.get(key)
+    return getattr(params, key, None)
+
+
+# ---------------------------------------------------------------------------
+# Capability builder
+# ---------------------------------------------------------------------------
+
+
+class _TaskCapability:
+    """The live task/delegate capability — structurally an ``AgentTool``."""
+
+    name = "task"
+    label = "Delegate task"
+    parameters: Schema = _TASK_PARAMS
+
+    def __init__(self, runner: DelegateRunner | None) -> None:
+        self._runner = runner
+        self.description = _base_description(_list_agents(runner))
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        params: object,
+        signal: object = None,
+        on_update: object = None,
+    ) -> AgentToolResult:
+        del tool_call_id, on_update
+        agent_raw = _field(params, "agent")
+        agent = agent_raw if isinstance(agent_raw, str) else None
+        if self._runner is None:
+            return AgentToolResult(
+                content=(TextContent(text=_STUB_NOTE),),
+                details=TaskDetails(delegated=False, ok=False, agent=agent),
+                isError=True,
+            )
+        objective = _field(params, "objective")
+        if not isinstance(objective, str) or objective == "":
+            return AgentToolResult(
+                content=(
+                    TextContent(text="`objective` is required to delegate a task."),
+                ),
+                details=TaskDetails(delegated=False, ok=False, agent=agent),
+                isError=True,
+            )
+        context_raw = _field(params, "context")
+        context = context_raw if isinstance(context_raw, str) else None
+        result = await self._runner.run(
+            DelegateRequest(objective=objective, agent=agent, context=context),
+            signal,
+        )
+        return AgentToolResult(
+            content=(TextContent(text=result.report),),
+            details=TaskDetails(delegated=True, ok=result.ok, agent=agent),
+            isError=not result.ok,
+        )
+
+
+def build_task_capability(ctx: DeckContext) -> _TaskCapability:
+    """Build the task/delegate capability.
+
+    If a :class:`DelegateRunner` is present on the context it is bound and the
+    tool truly delegates; otherwise the tool builds anyway and returns a
+    typed, non-throwing stub result so the deck stays assemblable in every
+    environment.
+
+    :param ctx: the deck context; an optional delegate runner is read from
+        ``ctx.framework[DELEGATE_HANDLE_KEY]``
+    """
+    return _TaskCapability(_read_delegate_runner(ctx))
+
+
+def _build(ctx: DeckContext) -> Capability:
+    return build_task_capability(ctx)
+
+
+#: Catalog row for the task/delegate capability.
+task_card = CapabilityCard(
+    id=capability_id("task"),
+    title="Delegate task",
+    summary="Hand a self-contained objective to a sub-agent and receive one report back.",
+    build=_build,
+)

induscode/capability_deck/cards/todo.py

@@ -0,0 +1,312 @@
+"""Todo capability — an in-memory checklist the agent sets/reads during a run.
+
+App-novel and framework-agnostic: the store is a plain in-process tuple of
+items, owned by the card and closed over by the built capability. No file
+persistence, no session-branch reconstruction, no framework store — just a
+mutable list the agent rewrites wholesale (the model is expected to send the
+complete desired list on every ``set``, the same convention coding agents use
+so the plan stays a single coherent snapshot rather than a diff stream).
+
+Two operations are folded into one tool keyed by an ``action`` discriminant:
+
+- ``read`` — return the current checklist as model-facing prose.
+- ``set``  — replace the checklist with the supplied items (the authoritative
+  new plan), then echo it back.
+
+The card produces a :data:`Capability` (the framework ``AgentTool`` shape) so
+the conductor consumes it verbatim as one of ``options.tools``.
+
+Port note — TypeBox → dict-literal JSON Schema + runtime guards
+---------------------------------------------------------------
+The TS card's TypeBox schema becomes a plain JSON-schema mapping (the
+framework's ``parameters: Mapping`` convention), and the compile-time
+``Static`` typing it bought is replaced by defensive runtime guards: a
+malformed ``action`` or ``items`` yields an ``isError`` result instead of an
+exception, because nothing upstream is guaranteed to have validated the
+model's arguments.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from indusagi.agent import AgentToolResult
+from indusagi.ai import TextContent
+
+from ..contract import Capability, CapabilityCard, DeckContext, Schema, capability_id
+
+__all__ = [
+    "TodoDetails",
+    "TodoItem",
+    "TodoLedger",
+    "TodoState",
+    "TodoWeight",
+    "build_todo_capability",
+    "todo_card",
+]
+
+
+# ---------------------------------------------------------------------------
+# Store (in-memory, card-owned)
+# ---------------------------------------------------------------------------
+
+#: Lifecycle state of one checklist item.
+TodoState: TypeAlias = Literal["pending", "active", "done", "dropped"]
+
+#: Relative importance of one checklist item.
+TodoWeight: TypeAlias = Literal["low", "normal", "high"]
+
+_STATES: tuple[TodoState, ...] = ("pending", "active", "done", "dropped")
+_WEIGHTS: tuple[TodoWeight, ...] = ("low", "normal", "high")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TodoItem:
+    """One row of the in-memory checklist."""
+
+    # The work to be done, phrased as a short imperative.
+    task: str
+    # Where the item stands right now.
+    state: TodoState
+    # How much it matters relative to the rest of the list.
+    weight: TodoWeight
+
+
+class TodoLedger:
+    """A minimal in-process checklist store.
+
+    Deliberately tiny and synchronous: the whole list lives in one field,
+    :meth:`set` swaps it atomically, and :meth:`read` hands back an immutable
+    tuple so a caller cannot mutate the store's backing sequence. One store is
+    created per built capability, so two sessions never share a checklist.
+    """
+
+    def __init__(self) -> None:
+        self._items: tuple[TodoItem, ...] = ()
+
+    def set(self, next_items: Sequence[TodoItem]) -> tuple[TodoItem, ...]:
+        """Replace the entire checklist with ``next_items``; returns the
+        stored snapshot."""
+        self._items = tuple(next_items)
+        return self._items
+
+    def read(self) -> tuple[TodoItem, ...]:
+        """Return the current checklist as an immutable snapshot."""
+        return self._items
+
+
+# ---------------------------------------------------------------------------
+# Parameters (dict-literal JSON Schema)
+# ---------------------------------------------------------------------------
+
+_TODO_ITEM_SCHEMA: Schema = {
+    "type": "object",
+    "properties": {
+        "task": {
+            "type": "string",
+            "description": "Short imperative description of the work item.",
+        },
+        "state": {
+            "type": "string",
+            "enum": list(_STATES),
+            "description": "Lifecycle state of the item.",
+        },
+        "weight": {
+            "type": "string",
+            "enum": list(_WEIGHTS),
+            "description": "Relative importance of the item.",
+        },
+    },
+    "required": ["task", "state", "weight"],
+    "additionalProperties": False,
+}
+
+_TODO_PARAMS: Schema = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "enum": ["read", "set"],
+            "description": (
+                "`read` returns the current checklist; `set` replaces it with "
+                "the items you provide."
+            ),
+        },
+        "items": {
+            "type": "array",
+            "items": _TODO_ITEM_SCHEMA,
+            "description": (
+                "The complete desired checklist. Required for `set` (send the "
+                "whole list, not a delta); ignored for `read`."
+            ),
+        },
+    },
+    "required": ["action"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TodoDetails:
+    """Structured detail returned alongside the model-facing content."""
+
+    # The action that was performed.
+    action: Literal["read", "set"]
+    # The checklist as it stands after the call.
+    items: tuple[TodoItem, ...]
+
+
+_TODO_DESCRIPTION = (
+    'Maintain a working checklist for the current task. Call with `action:"set"` and a '
+    "complete `items` list to record or revise your plan — always send the full intended "
+    'list, since the previous one is discarded. Call with `action:"read"` to recall the '
+    "current plan. Mark items `active` while in progress and `done` when finished so the "
+    "list reflects real status; use `dropped` for work you decided to skip."
+)
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+_STATE_GLYPH: Mapping[str, str] = {
+    "pending": "[ ]",
+    "active": "[~]",
+    "done": "[x]",
+    "dropped": "[-]",
+}
+
+
+def _render_checklist(items: Sequence[TodoItem]) -> str:
+    if not items:
+        return "The checklist is empty."
+    lines = []
+    for item in items:
+        weight = "" if item.weight == "normal" else f" ({item.weight})"
+        lines.append(f"{_STATE_GLYPH[item.state]} {item.task}{weight}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Runtime guards (the Static<typeof TodoParams> stand-in)
+# ---------------------------------------------------------------------------
+
+
+def _field(params: object, key: str) -> object:
+    """Read one argument off the model's params, whether they arrived as a
+    mapping (the wire form) or an attribute-bearing object (direct callers)."""
+    if isinstance(params, Mapping):
+        return params.get(key)
+    return getattr(params, key, None)
+
+
+def _parse_items(raw: object) -> tuple[TodoItem, ...]:
+    """Validate and coerce the ``items`` argument; raises :class:`ValueError`
+    on any shape the schema would have rejected."""
+    if raw is None:
+        return ()
+    if not isinstance(raw, Sequence) or isinstance(raw, (str, bytes)):
+        raise ValueError("`items` must be an array of checklist items.")
+    items: list[TodoItem] = []
+    for entry in raw:
+        if isinstance(entry, TodoItem):
+            items.append(entry)
+            continue
+        if not isinstance(entry, Mapping):
+            raise ValueError("each checklist item must be an object.")
+        task = entry.get("task")
+        if not isinstance(task, str) or task == "":
+            raise ValueError("each checklist item requires a `task` string.")
+        state = entry.get("state")
+        if state not in _STATES:
+            raise ValueError(
+                "each checklist item requires a `state` of "
+                "pending | active | done | dropped."
+            )
+        weight = entry.get("weight")
+        if weight not in _WEIGHTS:
+            raise ValueError(
+                "each checklist item requires a `weight` of low | normal | high."
+            )
+        items.append(TodoItem(task=task, state=state, weight=weight))
+    return tuple(items)
+
+
+# ---------------------------------------------------------------------------
+# Capability builder
+# ---------------------------------------------------------------------------
+
+
+class _TodoCapability:
+    """The live todo capability — structurally an ``AgentTool``."""
+
+    name = "todo"
+    label = "Checklist"
+    description = _TODO_DESCRIPTION
+    parameters: Schema = _TODO_PARAMS
+
+    def __init__(self) -> None:
+        self._ledger = TodoLedger()
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        params: object,
+        signal: object = None,
+        on_update: object = None,
+    ) -> AgentToolResult:
+        del tool_call_id, signal, on_update
+        action = _field(params, "action")
+        if action not in ("read", "set"):
+            return AgentToolResult(
+                content=(TextContent(text='`action` must be "read" or "set".'),),
+                details=None,
+                isError=True,
+            )
+        if action == "set":
+            try:
+                items = self._ledger.set(_parse_items(_field(params, "items")))
+            except ValueError as bad:
+                return AgentToolResult(
+                    content=(TextContent(text=str(bad)),),
+                    details=None,
+                    isError=True,
+                )
+            heading = "Checklist updated:"
+        else:
+            items = self._ledger.read()
+            heading = "Current checklist:"
+        text = f"{heading}\n{_render_checklist(items)}"
+        return AgentToolResult(
+            content=(TextContent(text=text),),
+            details=TodoDetails(action=action, items=items),
+        )
+
+
+def build_todo_capability(_ctx: DeckContext) -> _TodoCapability:
+    """Build the todo capability, binding it to a freshly created in-memory
+    ledger.
+
+    The ledger is owned by the returned capability, so the checklist persists
+    for the life of this capability instance (i.e. the session) without any
+    external store.
+
+    :param _ctx: the deck context (unused — the todo card needs no
+        cwd/backends)
+    """
+    return _TodoCapability()
+
+
+def _build(ctx: DeckContext) -> Capability:
+    return build_todo_capability(ctx)
+
+
+#: Catalog row for the todo capability — registered in ``APP_NOVEL_CARDS``.
+todo_card = CapabilityCard(
+    id=capability_id("todo"),
+    title="Checklist",
+    summary="Keep an in-memory checklist of the current task's steps; set or read it.",
+    build=_build,
+)