induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/cards/__init__.py

@@ -0,0 +1,116 @@
+"""Capability cards — the app-novel capabilities the deck builds in-house.
+
+Each card is a :class:`CapabilityCard`: metadata plus a ``build(ctx)`` factory
+that mints a live :data:`Capability` (the framework ``AgentTool`` shape) for a
+working context. These are written fresh against the framework contract — not
+derived from any prior tooling layer — and stay framework-agnostic where the
+behavior is original (todo and bg-process wrap only the stdlib + the deck
+contract).
+
+The connector and memory cards expose a thin, clearly-typed adapter seam over
+a framework handle injected through :attr:`DeckContext.framework`; when no
+handle is wired they degrade to a typed stub so every card builds and runs in
+any environment, including tests.
+
+:data:`APP_NOVEL_CARDS` is the contribution this package makes to the catalog;
+the provisioner's profile table concatenates it onto the builtin-bridge cards
+(the framework's file/shell/search/web tools) for the ``all`` profile.
+
+Port note: the TS barrel also exported the ``Static``-derived
+``XxxParamsType`` aliases; those compile-time types have no Python analogue
+(parameters are plain JSON-schema mappings — see the deck contract's port
+note) and are dropped here. Everything else is exported 1:1, snake_cased.
+"""
+
+from __future__ import annotations
+
+from ..contract import CapabilityCard
+from .bg_process import (
+    DaemonDetails,
+    DaemonState,
+    DaemonTable,
+    build_daemon_capability,
+    daemon_card,
+)
+from .memory import (
+    InMemoryStore,
+    MEMORY_HANDLE_KEY,
+    MemoryDetails,
+    MemoryStore,
+    build_memory_capability,
+    memory_card,
+)
+from .saas import (
+    RemoteExecution,
+    RemoteToolSummary,
+    SAAS_GATEWAY_KEY,
+    SaasDetails,
+    SaasGatewayPort,
+    build_saas_capability,
+    saas_card,
+)
+from .task import (
+    DELEGATE_HANDLE_KEY,
+    DelegateRequest,
+    DelegateResult,
+    DelegateRunner,
+    TaskDetails,
+    build_task_capability,
+    task_card,
+)
+from .todo import (
+    TodoDetails,
+    TodoItem,
+    TodoLedger,
+    TodoState,
+    TodoWeight,
+    build_todo_capability,
+    todo_card,
+)
+
+__all__ = [
+    "APP_NOVEL_CARDS",
+    "DELEGATE_HANDLE_KEY",
+    "DaemonDetails",
+    "DaemonState",
+    "DaemonTable",
+    "DelegateRequest",
+    "DelegateResult",
+    "DelegateRunner",
+    "InMemoryStore",
+    "MEMORY_HANDLE_KEY",
+    "MemoryDetails",
+    "MemoryStore",
+    "RemoteExecution",
+    "RemoteToolSummary",
+    "SAAS_GATEWAY_KEY",
+    "SaasDetails",
+    "SaasGatewayPort",
+    "TaskDetails",
+    "TodoDetails",
+    "TodoItem",
+    "TodoLedger",
+    "TodoState",
+    "TodoWeight",
+    "build_daemon_capability",
+    "build_memory_capability",
+    "build_saas_capability",
+    "build_task_capability",
+    "build_todo_capability",
+    "daemon_card",
+    "memory_card",
+    "saas_card",
+    "task_card",
+    "todo_card",
+]
+
+#: The app-novel cards, in catalog order. The provisioner's profile table
+#: concatenates these onto the builtin-bridge selection for the ``all``
+#: profile.
+APP_NOVEL_CARDS: tuple[CapabilityCard, ...] = (
+    todo_card,
+    daemon_card,
+    task_card,
+    saas_card,
+    memory_card,
+)

induscode/capability_deck/cards/bg_process.py

@@ -0,0 +1,482 @@
+"""Background-process capability — start, poll, and stop long-lived child
+processes that outlive a single tool call.
+
+App-novel and framework-agnostic: it wraps :func:`asyncio.create_subprocess_shell`
+directly rather than delegating to any framework process controller, so the
+lifecycle is owned entirely by this card. A long-running command (a dev
+server, a watcher, a build in ``--watch`` mode) is launched detached from the
+tool turn; the agent later polls its captured output or signals it to stop.
+
+One tool folds the lifecycle into an ``action`` discriminant:
+
+- ``start`` — spawn ``command`` in a shell, return the assigned handle id.
+- ``poll``  — return the buffered stdout/stderr (and live/exited status) for a
+  handle, optionally only the lines appended since the last poll.
+- ``stop``  — send SIGTERM (escalating to SIGKILL after a grace window) to a
+  handle's process.
+- ``list``  — enumerate every handle this capability is tracking.
+
+Output is captured into bounded ring buffers so a chatty process cannot grow
+memory without limit; only the most recent lines are retained. The card
+produces a :data:`Capability` (framework ``AgentTool``) the conductor consumes.
+
+Port notes (TS ``cards/bg-process-card.ts`` → asyncio):
+
+- Node's sync ``spawn`` becomes the awaited ``create_subprocess_shell``, so
+  :meth:`DaemonTable.start` is a coroutine — ``execute`` is async anyway.
+- The stdout/stderr ``data`` listeners become two reader tasks per handle,
+  each pumping decoded chunks into its ring buffer; the ``exit`` listener
+  becomes a waiter task recording terminal state (a negative ``returncode``
+  maps to the TS ``signalled`` branch, with the signal *name* recovered).
+- The TS ``graceMs = 3000`` SIGTERM→SIGKILL escalation is kept verbatim as
+  ``grace = 3.0`` seconds; like the TS original, ``stop`` resolves as soon as
+  the kill is sent rather than waiting again.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import signal as _signal
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+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__ = [
+    "DaemonDetails",
+    "DaemonState",
+    "DaemonTable",
+    "build_daemon_capability",
+    "daemon_card",
+]
+
+
+# ---------------------------------------------------------------------------
+# Process table (in-memory, card-owned)
+# ---------------------------------------------------------------------------
+
+#: Coarse lifecycle state of a tracked background process.
+DaemonState: TypeAlias = Literal["running", "exited", "signalled"]
+
+_MAX_BUFFERED_LINES = 2_000
+
+_LINE_SPLIT = re.compile(r"\r?\n")
+
+
+@dataclass(slots=True)
+class _RingBuffer:
+    """A bounded buffer of recent output lines for one stream."""
+
+    lines: list[str] = field(default_factory=list)
+    # Index of the next unread line for incremental polling.
+    cursor: int = 0
+
+
+def _push_lines(buf: _RingBuffer, chunk: str) -> None:
+    # Split on newlines; keeping partials joined to the last buffered line is
+    # overkill here (the TS card made the same call) — each chunk's lines are
+    # treated as discrete and the buffer is clipped to the cap.
+    for line in _LINE_SPLIT.split(chunk):
+        if line:
+            buf.lines.append(line)
+    if len(buf.lines) > _MAX_BUFFERED_LINES:
+        drop = len(buf.lines) - _MAX_BUFFERED_LINES
+        del buf.lines[:drop]
+        buf.cursor = max(0, buf.cursor - drop)
+
+
+@dataclass(slots=True)
+class DaemonHandle:
+    """One tracked background process and its captured state."""
+
+    id: str
+    command: str
+    proc: asyncio.subprocess.Process
+    state: DaemonState
+    exit_code: int | None
+    signal: str | None
+    started_at: int
+    stdout: _RingBuffer
+    stderr: _RingBuffer
+    # The reader tasks pumping the pipes, plus the exit waiter.
+    pumps: tuple[asyncio.Task[None], ...] = ()
+    waiter: asyncio.Task[None] | None = None
+
+
+def _signal_name(signum: int) -> str:
+    try:
+        return _signal.Signals(signum).name
+    except ValueError:
+        return f"SIG{signum}"
+
+
+async def _pump(stream: asyncio.StreamReader, buf: _RingBuffer) -> None:
+    """Read a pipe to EOF, feeding decoded chunks into the ring buffer."""
+    while True:
+        chunk = await stream.read(8192)
+        if not chunk:
+            return
+        _push_lines(buf, chunk.decode("utf-8", errors="replace"))
+
+
+class DaemonTable:
+    """An in-process table of background children, owned by one built
+    capability.
+
+    Each :meth:`start` spawns a shell-wrapped child, wires its stdout/stderr
+    into bounded buffers via reader tasks, and records terminal state when the
+    process exits. :meth:`stop` escalates from SIGTERM to SIGKILL if the
+    process does not exit within a grace window. The table is per-capability,
+    so one session's daemons are isolated from another's.
+    """
+
+    def __init__(self, cwd: str) -> None:
+        self._cwd = cwd
+        self._handles: dict[str, DaemonHandle] = {}
+        self._next_seq = 1
+
+    async def start(self, command: str) -> DaemonHandle:
+        """Spawn ``command`` in a shell under the table's cwd and begin
+        capturing its output."""
+        handle_id = f"bg-{self._next_seq}"
+        self._next_seq += 1
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            cwd=self._cwd,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        handle = DaemonHandle(
+            id=handle_id,
+            command=command,
+            proc=proc,
+            state="running",
+            exit_code=None,
+            signal=None,
+            started_at=int(time.time() * 1000),
+            stdout=_RingBuffer(),
+            stderr=_RingBuffer(),
+        )
+        pumps: list[asyncio.Task[None]] = []
+        if proc.stdout is not None:
+            pumps.append(asyncio.create_task(_pump(proc.stdout, handle.stdout)))
+        if proc.stderr is not None:
+            pumps.append(asyncio.create_task(_pump(proc.stderr, handle.stderr)))
+        handle.pumps = tuple(pumps)
+        handle.waiter = asyncio.create_task(self._watch_exit(handle))
+        self._handles[handle_id] = handle
+        return handle
+
+    @staticmethod
+    async def _watch_exit(handle: DaemonHandle) -> None:
+        """Record terminal state once the child exits — the TS ``exit``
+        listener. A negative returncode means the child was signalled (Node
+        reported ``code=null, signal="SIGTERM"`` for the same case)."""
+        code = await handle.proc.wait()
+        if code < 0:
+            handle.exit_code = None
+            handle.signal = _signal_name(-code)
+            handle.state = "signalled"
+        else:
+            handle.exit_code = code
+            handle.signal = None
+            handle.state = "exited"
+
+    def get(self, id: str) -> DaemonHandle | None:
+        return self._handles.get(id)
+
+    def list(self) -> list[DaemonHandle]:
+        return list(self._handles.values())
+
+    async def stop(self, handle: DaemonHandle, grace: float = 3.0) -> None:
+        """Signal a handle's process to terminate. Sends SIGTERM immediately
+        and a SIGKILL after ``grace`` seconds if the child is still alive.
+        Resolves once the child has exited or the kill has been sent."""
+        if handle.state != "running":
+            return
+        try:
+            handle.proc.terminate()
+        except ProcessLookupError:
+            # Already gone; the waiter records the terminal state.
+            return
+        waiter = handle.waiter
+        if waiter is None:  # pragma: no cover — start always wires a waiter
+            return
+        try:
+            # Shield: a grace timeout must not cancel the exit recorder.
+            await asyncio.wait_for(asyncio.shield(waiter), grace)
+        except TimeoutError:
+            if handle.state == "running":
+                try:
+                    handle.proc.kill()
+                except ProcessLookupError:
+                    pass
+            return
+        # The child exited within the grace window; drain the readers so no
+        # task outlives the call (they end promptly at pipe EOF).
+        if handle.pumps:
+            await asyncio.gather(*handle.pumps, return_exceptions=True)
+
+
+# ---------------------------------------------------------------------------
+# Parameters (dict-literal JSON Schema)
+# ---------------------------------------------------------------------------
+
+_DAEMON_PARAMS: Schema = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "enum": ["start", "poll", "stop", "list"],
+            "description": (
+                "`start` launches a long-running command; `poll` reads its captured "
+                "output; `stop` terminates it; `list` shows all tracked processes."
+            ),
+        },
+        "command": {
+            "type": "string",
+            "description": "Shell command to launch. Required for `start`.",
+        },
+        "id": {
+            "type": "string",
+            "description": "Handle returned by `start`. Required for `poll` and `stop`.",
+        },
+        "sinceLast": {
+            "type": "boolean",
+            "description": (
+                "On `poll`, return only output appended since the previous poll of "
+                "this handle. Defaults to false (return the full retained buffer)."
+            ),
+        },
+    },
+    "required": ["action"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _DaemonRow:
+    """One row of a ``list`` result's structured detail."""
+
+    id: str
+    command: str
+    state: DaemonState
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DaemonDetails:
+    """Structured detail returned alongside the model-facing content."""
+
+    action: Literal["start", "poll", "stop", "list"]
+    ok: bool
+    id: str | None = None
+    state: DaemonState | None = None
+    exit_code: int | None = None
+    processes: tuple[_DaemonRow, ...] | None = None
+
+
+_DAEMON_DESCRIPTION = (
+    "Run and manage long-lived background processes that persist across tool calls — dev "
+    "servers, file watchers, anything you start once and observe over time. Use "
+    '`action:"start"` with a `command` to launch one (you get back a handle `id`), '
+    '`action:"poll"` with that `id` to read its accumulated output, `action:"stop"` to '
+    'terminate it, and `action:"list"` to see what is running. Do NOT use this for '
+    "ordinary one-shot commands that finish on their own — run those with the shell tool."
+)
+
+
+# ---------------------------------------------------------------------------
+# Output rendering
+# ---------------------------------------------------------------------------
+
+
+def _drain_buffer(buf: _RingBuffer, since_last: bool) -> list[str]:
+    if since_last:
+        fresh = buf.lines[buf.cursor :]
+        buf.cursor = len(buf.lines)
+        return fresh
+    return list(buf.lines)
+
+
+def _status_line(handle: DaemonHandle) -> str:
+    if handle.state == "running":
+        return "running"
+    if handle.state == "signalled":
+        return f"signalled ({handle.signal if handle.signal is not None else '?'})"
+    code = handle.exit_code if handle.exit_code is not None else "?"
+    return f"exited (code {code})"
+
+
+def _field(params: object, key: str) -> object:
+    if isinstance(params, Mapping):
+        return params.get(key)
+    return getattr(params, key, None)
+
+
+def _err_result(
+    action: Literal["start", "poll", "stop", "list"], message: str
+) -> AgentToolResult:
+    return AgentToolResult(
+        content=(TextContent(text=message),),
+        details=DaemonDetails(action=action, ok=False),
+        isError=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Capability builder
+# ---------------------------------------------------------------------------
+
+
+class _DaemonCapability:
+    """The live background-process capability — structurally an ``AgentTool``."""
+
+    name = "bg-process"
+    label = "Background process"
+    description = _DAEMON_DESCRIPTION
+    parameters: Schema = _DAEMON_PARAMS
+
+    def __init__(self, cwd: str) -> None:
+        self._table = DaemonTable(cwd)
+
+    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 == "start":
+            command = _field(params, "command")
+            if not isinstance(command, str) or command == "":
+                return _err_result(
+                    "start", "`command` is required to start a background process."
+                )
+            try:
+                handle = await self._table.start(command)
+            except Exception as bad:  # defensive: a spawn failure names itself
+                return _err_result("start", f"spawn error: {bad}")
+            return AgentToolResult(
+                content=(
+                    TextContent(
+                        text=(
+                            f"Started background process {handle.id}: {handle.command}\n"
+                            f'Poll it with action:"poll", id:"{handle.id}".'
+                        )
+                    ),
+                ),
+                details=DaemonDetails(
+                    action="start", ok=True, id=handle.id, state=handle.state
+                ),
+            )
+        if action == "poll":
+            raw_id = _field(params, "id")
+            handle = self._table.get(raw_id) if isinstance(raw_id, str) else None
+            if handle is None:
+                shown = raw_id if isinstance(raw_id, str) else ""
+                return _err_result("poll", f'No background process with id "{shown}".')
+            since_last = bool(_field(params, "sinceLast") or False)
+            out = _drain_buffer(handle.stdout, since_last)
+            err = _drain_buffer(handle.stderr, since_last)
+            parts = [f"Process {handle.id} — {_status_line(handle)}"]
+            if out:
+                parts.append("--- stdout ---\n" + "\n".join(out))
+            if err:
+                parts.append("--- stderr ---\n" + "\n".join(err))
+            if not out and not err:
+                parts.append("(no new output)")
+            return AgentToolResult(
+                content=(TextContent(text="\n".join(parts)),),
+                details=DaemonDetails(
+                    action="poll",
+                    ok=True,
+                    id=handle.id,
+                    state=handle.state,
+                    exit_code=handle.exit_code,
+                ),
+            )
+        if action == "stop":
+            raw_id = _field(params, "id")
+            handle = self._table.get(raw_id) if isinstance(raw_id, str) else None
+            if handle is None:
+                shown = raw_id if isinstance(raw_id, str) else ""
+                return _err_result("stop", f'No background process with id "{shown}".')
+            await self._table.stop(handle)
+            return AgentToolResult(
+                content=(
+                    TextContent(
+                        text=(
+                            f"Stopped background process {handle.id} "
+                            f"({_status_line(handle)})."
+                        )
+                    ),
+                ),
+                details=DaemonDetails(
+                    action="stop",
+                    ok=True,
+                    id=handle.id,
+                    state=handle.state,
+                    exit_code=handle.exit_code,
+                ),
+            )
+        if action == "list":
+            handles = self._table.list()
+            text = (
+                "No background processes are being tracked."
+                if not handles
+                else "\n".join(
+                    f"{h.id} [{_status_line(h)}] {h.command}" for h in handles
+                )
+            )
+            return AgentToolResult(
+                content=(TextContent(text=text),),
+                details=DaemonDetails(
+                    action="list",
+                    ok=True,
+                    processes=tuple(
+                        _DaemonRow(id=h.id, command=h.command, state=h.state)
+                        for h in handles
+                    ),
+                ),
+            )
+        return AgentToolResult(
+            content=(
+                TextContent(
+                    text='`action` must be "start", "poll", "stop", or "list".'
+                ),
+            ),
+            details=None,
+            isError=True,
+        )
+
+
+def build_daemon_capability(ctx: DeckContext) -> _DaemonCapability:
+    """Build the background-process capability, binding it to a fresh
+    per-session :class:`DaemonTable` scoped to the context's working
+    directory.
+
+    :param ctx: the deck context — its ``cwd`` is where launched processes run
+    """
+    return _DaemonCapability(ctx.cwd)
+
+
+def _build(ctx: DeckContext) -> Capability:
+    return build_daemon_capability(ctx)
+
+
+#: Catalog row for the background-process capability.
+daemon_card = CapabilityCard(
+    id=capability_id("bg-process"),
+    title="Background process",
+    summary="Start, poll, and stop long-lived child processes that span multiple turns.",
+    build=_build,
+)