nustd 0.2.0__py3-none-any.whl

nu/cc/__init__.py

@@ -0,0 +1,36 @@
+"""Nu Claude Code fabric.
+
+Surface:
+    - CCFabric: holds a ClaudeAgentOptions template + runs one query per prompt call.
+    - PromptRef: MethodRef for a Claude Code prompt endpoint on a Service.
+    - CCPrompt: the interaction produced when a PromptRef is called.
+    - bind(service_cls, **options): Provide the CCFabric tagged by the Service class.
+    - Session: bracket that makes every prompt inside it continue one conversation.
+
+Both sync and async are supported; prefer `nu.arun` for real use so cc calls
+don't block the event loop (streaming, UI ticks, parallel prompts all need it).
+Sync is fine for one-off scripts.
+
+Example::
+
+    class Agent(nu.Service):
+        ask = nu.cc.PromptRef.method()
+
+    app = nu.With(
+        nu.cc.bind(Agent, model="claude-sonnet-4-5", permission_mode="acceptEdits"),
+        body=nu.print(nu.Dict(Agent.ask(prompt="write a haiku about rust"))["text"]),
+    )
+
+    asyncio.run(nu.arun(app))
+"""
+
+from __future__ import annotations
+
+from .fabric import CCFabric
+from .interactions import CCPrompt
+from .presets import bind
+from .refs import PromptRef
+from .session import Session, SessionHandle
+
+
+__all__ = ["CCFabric", "CCPrompt", "PromptRef", "Session", "SessionHandle", "bind"]

nu/cc/core.py

@@ -0,0 +1,70 @@
+"""Shared compile thunks: merge defaults + call args, dispatch through CCFabric."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from .fabric import CCFabric
+from .session import SessionHandle
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from nu.lang.runtime import Runtime
+
+
+__all__ = ["acompile_call", "compile_call"]
+
+
+def _split(payload: dict, args: dict) -> tuple[str, dict]:
+    """Pull `prompt` out; merge endpoint defaults under call overrides."""
+    call = dict(args)
+    prompt = call.pop("prompt")
+    merged = {**payload.get("defaults", {}), **call}
+    return str(prompt), merged
+
+
+def _session(rt: Runtime) -> SessionHandle | None:
+    return rt.ctx.get(SessionHandle) if rt.ctx.has(SessionHandle) else None
+
+
+def compile_call(children: tuple[Callable, ...]) -> Callable:
+    """Sync compile: wraps the async fabric call in asyncio.run."""
+    ref_thunk, args_thunk = children
+
+    def thunk(rt: Runtime) -> object:
+        payload = ref_thunk(rt)
+        args = args_thunk(rt)
+        prompt, overrides = _split(payload, args)
+        fabric = rt.ctx.get(CCFabric, payload["owner_service"])
+        handle = _session(rt)
+        if handle is not None and handle.session_id:
+            overrides.setdefault("resume", handle.session_id)
+        result = asyncio.run(fabric.aprompt(prompt, **overrides))
+        if handle is not None and result.get("session_id"):
+            handle.session_id = result["session_id"]
+        return result
+
+    return thunk
+
+
+def acompile_call(children: tuple[Callable, ...]) -> Callable:
+    """Async compile: dispatch through CCFabric."""
+    ref_thunk, args_thunk = children
+
+    async def athunk(rt: Runtime) -> object:
+        payload = await ref_thunk(rt)
+        args = await args_thunk(rt)
+        prompt, overrides = _split(payload, args)
+        fabric = rt.ctx.get(CCFabric, payload["owner_service"])
+        handle = _session(rt)
+        if handle is not None and handle.session_id:
+            overrides.setdefault("resume", handle.session_id)
+        result = await fabric.aprompt(prompt, **overrides)
+        if handle is not None and result.get("session_id"):
+            handle.session_id = result["session_id"]
+        return result
+
+    return athunk

nu/cc/fabric.py

@@ -0,0 +1,72 @@
+"""CCFabric: config template + one async call into claude-agent-sdk.
+
+Holds the default ClaudeAgentOptions (model, cwd, tools, system prompt, ...) for a
+bound Service. Per-call overrides merge on top. `aprompt` runs one query and
+collects the assistant's final text + the ResultMessage metadata.
+"""
+
+from __future__ import annotations
+
+from dataclasses import fields, replace
+from typing import TYPE_CHECKING, Any
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ResultMessage,
+    TextBlock,
+    query,
+)
+
+
+if TYPE_CHECKING:
+    from nu.lang.runtime import Context
+
+
+__all__ = ["CCFabric"]
+
+
+class CCFabric:
+    """Holds a ClaudeAgentOptions template. One query per prompt call."""
+
+    def __init__(self, *, options: ClaudeAgentOptions | None = None, **defaults: object) -> None:
+        self.options = options or ClaudeAgentOptions(**defaults)  # type: ignore[arg-type]
+
+    def setup(self, ctx: Context) -> None:  # noqa: D102
+        pass
+
+    def cleanup(self) -> None:  # noqa: D102
+        pass
+
+    async def asetup(self, ctx: Context) -> None:  # noqa: D102
+        pass
+
+    async def acleanup(self) -> None:  # noqa: D102
+        pass
+
+    def _merge(self, overrides: dict[str, object]) -> ClaudeAgentOptions:
+        if not overrides:
+            return self.options
+        allowed = {f.name for f in fields(self.options)}
+        clean = {k: v for k, v in overrides.items() if k in allowed and v is not None}
+        return replace(self.options, **clean) if clean else self.options
+
+    async def aprompt(self, prompt: str, **overrides: object) -> dict[str, Any]:
+        """Run one prompt turn. Returns {text, session_id, total_cost_usd, duration_ms, num_turns}."""
+        opts = self._merge(overrides)
+        text_parts: list[str] = []
+        meta: dict[str, Any] = {}
+        async for msg in query(prompt=prompt, options=opts):
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock):
+                        text_parts.append(block.text)
+            elif isinstance(msg, ResultMessage):
+                meta = {
+                    "session_id": getattr(msg, "session_id", None),
+                    "total_cost_usd": getattr(msg, "total_cost_usd", None),
+                    "duration_ms": getattr(msg, "duration_ms", None),
+                    "num_turns": getattr(msg, "num_turns", None),
+                    "result": getattr(msg, "result", None),
+                }
+        return {"text": meta.get("result") or "".join(text_parts), **meta}

nu/cc/interactions.py

@@ -0,0 +1,71 @@
+"""CCPrompt: ScalarAction that runs one Claude Code prompt turn."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from nu.engine.structure import Declared
+from nu.lang import ScalarAction
+
+from .core import acompile_call, compile_call
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+__all__ = ["CCPrompt"]
+
+
+class CCPrompt(ScalarAction):
+    """One prompt turn against the Claude Code agent a PromptRef addresses.
+
+    Built by calling a PromptRef rather than written by hand. At evaluation
+    it resolves the Ref, merges the endpoint's declared defaults under this
+    call's overrides, and drives one ``query`` through the ``CCFabric``
+    provided for the owning Service, draining the message stream to the end.
+
+    A whole agent run happens inside this one node: the agent may read
+    files, run tools and take many turns before the stream closes. Only the
+    final text and the run's accounting come back out.
+
+    Args:
+        ref: the PromptRef naming the agent.
+        args: a Dict carrying ``prompt`` plus this call's option overrides.
+
+    Notes:
+        - Declared as mutating its Ref child, so runs against one agent stay
+          ordered and are never folded together.
+        - Under a ``nu.cc.Session`` bracket it reads the session id off the
+          handle and resumes; the first call in the bracket starts fresh and
+          writes its id back for the rest.
+        - An explicit ``resume=`` override wins over the bracket's handle.
+        - The sync path drives the async SDK through ``asyncio.run``, so it
+          raises if a loop is already running. Use ``nu.arun`` anywhere near
+          an event loop.
+
+    Yields:
+        A dict with ``text`` plus the run's accounting: ``session_id``,
+        ``total_cost_usd``, ``duration_ms``, ``num_turns`` and the raw
+        ``result``. ``text`` is the SDK's final result string, falling back
+        to the concatenated assistant text blocks. If the stream ends
+        without a result message the accounting keys are absent entirely,
+        not None.
+
+    Example:
+        class Agent(nu.Service):
+            ask = nu.cc.PromptRef.method()
+        app = nu.With(
+            nu.cc.bind(Agent, model="claude-sonnet-4-5", permission_mode="acceptEdits"),
+            body=nu.print(nu.dict(Agent.ask("write a haiku about rust"))["text"]),
+        )
+        asyncio.run(nu.arun(app))
+    """
+
+    _mutates = Declared(value=frozenset({0}), name="mutates")
+
+    def _compile(self, nid: int, children: tuple[Callable, ...]) -> Callable:
+        return compile_call(children)
+
+    def _acompile(self, nid: int, children: tuple[Callable, ...]) -> Callable:
+        return acompile_call(children)

nu/cc/presets.py

@@ -0,0 +1,49 @@
+"""bind(): Provide a CCFabric for a Service."""
+
+from __future__ import annotations
+
+from nu.context.fabric import Provide
+
+from .fabric import CCFabric
+
+
+__all__ = ["bind"]
+
+
+def bind(service_cls: type, **defaults: object) -> Provide:
+    """Configure the Claude Code agent a Service's PromptRefs run against.
+
+    What it provides is tagged by the Service class, which is how a PromptRef
+    declared on that class finds its fabric, and how one program can run
+    several agents with different tools, directories or system prompts side
+    by side.
+
+    Args:
+        service_cls: the Service whose PromptRefs this agent serves.
+        **defaults: ``ClaudeAgentOptions`` fields - ``model``, ``cwd``,
+            ``allowed_tools``, ``system_prompt``, ``permission_mode``,
+            ``max_turns``, and the rest. Pass ``options=`` with a built
+            ``ClaudeAgentOptions`` instead to bypass the kwargs entirely.
+
+    Notes:
+        - The kwargs are ``ClaudeAgentOptions`` fields - ``model``, ``cwd``,
+          ``allowed_tools``, ``system_prompt``, ``permission_mode``,
+          ``max_turns`` and the rest - or a single ``options=`` holding a
+          built ``ClaudeAgentOptions``.
+        - These are the outermost layer: declaration defaults sit on top of
+          them and per-call overrides on top of those.
+        - Unlike the LLM fabric there is no client to open, so the
+          ``With`` block costs nothing until a prompt actually runs.
+        - Everything here reaches the ``ClaudeAgentOptions`` constructor as
+          written, so a bad key raises when the block is entered - unlike a
+          per-call override, which is dropped silently.
+        - ``options=`` and loose kwargs do not combine: given both, the
+          built options object is used and the kwargs are ignored.
+
+    Yields:
+        A Provide to hand to ``nu.With``.
+
+    Example:
+        app = nu.With(nu.cc.bind(Agent, model="claude-sonnet-4-5", cwd="/srv/repo"), body=...)
+    """
+    return Provide(CCFabric, defaults, tag=service_cls)

nu/cc/refs.py

@@ -0,0 +1,89 @@
+"""PromptRef: Ref addressing a Claude Code prompt endpoint on a Service.
+
+Mirrors nu.http verb refs: `.method(**defaults)` returns a Method declaration
+that the ServiceMeta descriptor unwraps at class access; calling the Ref with
+kwargs produces a CCPrompt interaction.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from nu.domains.service import Method, MethodRef
+from nu.forms import Dict
+
+from .interactions import CCPrompt
+
+
+if TYPE_CHECKING:
+    from nu.lang import Nu
+
+
+__all__ = ["PromptRef"]
+
+
+class PromptRef(MethodRef):
+    """Addresses a Claude Code agent on a Service, one Ref per agent role.
+
+    Written in a Service class body. The Ref carries no configuration of its
+    own beyond its declared defaults: the model, working directory, tool
+    allowlist and system prompt come from the ``CCFabric`` provided for the
+    owning Service class, so a program can hold several Services each
+    standing for a differently-configured agent.
+
+    Notes:
+        - Every call spawns a fresh Claude Code session unless it runs
+          inside a ``nu.cc.Session`` bracket, which threads the session id
+          through so the calls read as one conversation.
+        - The Ref needs the ``claude-agent-sdk`` package and a working
+          ``claude`` CLI on the machine that evaluates it.
+
+    Example:
+        class Agent(nu.Service):
+            ask = nu.cc.PromptRef.method(max_turns=1)
+        app = nu.With(
+            nu.cc.bind(Agent, model="claude-sonnet-4-5", cwd="/tmp"),
+            body=nu.print(nu.dict(Agent.ask("name this directory"))["text"]),
+        )
+        asyncio.run(nu.arun(app))
+    """
+
+    @classmethod
+    def method(cls, **defaults: object) -> PromptRef:  # type: ignore[override]
+        """Declare a prompt endpoint whose defaults every call through it inherits.
+
+        Args:
+            **defaults: ``ClaudeAgentOptions`` fields to apply on top of the
+                bind for calls through this endpoint (``model``,
+                ``max_turns``, ``allowed_tools``, ``permission_mode``, ...).
+                A per-call kwarg of the same name wins.
+
+        Notes:
+            - Annotated as returning the Ref, but at run time it returns a
+              ``Method`` declaration that the ServiceMeta descriptor unwraps
+              at class access. The lie makes ``Agent.ask`` type-check as a
+              PromptRef.
+            - Keys that are not ``ClaudeAgentOptions`` fields are dropped
+              silently when the call runs, so a misspelt option is not an
+              error, it is a no-op.
+        """
+        return Method(cls, defaults=defaults)  # type: ignore[return-value]
+
+    def __call__(self, prompt: object, **overrides: object) -> Nu:
+        """Build a CCPrompt interaction over one turn's prompt and options.
+
+        Args:
+            prompt: the text to send. Stringified at evaluation, so it may
+                be a Nu term rather than a literal.
+            **overrides: ``ClaudeAgentOptions`` fields for this call only.
+
+        Notes:
+            - Keywords beyond the prompt are ``ClaudeAgentOptions`` fields
+              applied to this call only.
+            - Unlike ChatRef, the prompt is positional and required: there
+              is no messages-list form, since the transcript is the
+              session's business rather than the caller's.
+            - Prompt and overrides land together in one ``Dict`` child, so
+              both are resolved at evaluation.
+        """
+        return CCPrompt(self, Dict.of(prompt=prompt, **overrides))

nu/cc/session.py

@@ -0,0 +1,99 @@
+"""Session: lifecycle bracket that scopes a cc session across nested prompts.
+
+Mirrors the nu.kv pattern (Snapshot / Transaction): a lazy handle is bound into
+the ctx on entry; every PromptRef call inside the bracket reads it and threads
+`resume=session_id` so cc treats the calls as one continuous session.
+
+The first prompt starts a fresh cc session (no resume); its returned session_id
+is captured on the handle, and subsequent prompts continue it.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from nu.flows.strategy import Sequential
+from nu.spans.bracket import _LifecycleBracket
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from nu.lang import Nu
+    from nu.lang.runtime import Context
+
+
+__all__ = ["Session", "SessionHandle"]
+
+
+class SessionHandle:
+    """The mutable cell a Session binds, holding the id once a prompt has produced one.
+
+    Empty until the first prompt inside the bracket returns; from then on
+    every prompt in the bracket reads the id off it and resumes. Bound in
+    the Context under its own type, which is how the compiled prompt thunks
+    find it without the Session being their parent.
+    """
+
+    __slots__ = ("session_id",)
+
+    def __init__(self) -> None:
+        self.session_id: str | None = None
+
+
+def _wrap_body(children: tuple[Nu, ...]) -> Nu:
+    if len(children) == 1:
+        return children[0]
+    return Sequential(*children)
+
+
+class Session(_LifecycleBracket):
+    """Makes every prompt in its body continue one Claude Code conversation.
+
+    Without it each prompt is a cold start that remembers nothing. The
+    bracket binds a fresh handle on entry; the first prompt underneath runs
+    without resuming and writes the id cc gave it onto the handle, and each
+    later prompt reads it back and resumes, so the agent keeps its context
+    across the whole body.
+
+    Args:
+        *body: the terms to run inside the session. Several are run in
+            order, as if wrapped in ``Sequential``.
+
+    Notes:
+        - Reach is by Context, not by ownership: any prompt evaluated
+          while the bracket is open joins the session, including ones
+          inside functions the body calls.
+        - A nested Session binds its own handle and shadows the outer one,
+          so its prompts form a separate conversation. Sibling Sessions
+          likewise never share.
+        - The handle is bound at the same point whether the run is sync or
+          async, so the bracket behaves the same under ``nu.run`` and
+          ``nu.arun``.
+        - Nothing is persisted. The id lives for as long as the bracket is
+          open; to pick a conversation back up later, keep the
+          ``session_id`` a prompt yielded and pass it as ``resume=``.
+
+    Yields:
+        Whatever the body yields; the bracket adds nothing of its own.
+
+    Example:
+        class Agent(nu.Service):
+            ask = nu.cc.PromptRef.method()
+        app = nu.With(
+            nu.cc.bind(Agent, model="claude-sonnet-4-5"),
+            body=nu.cc.Session(
+                nu.print(nu.dict(Agent.ask("pick a number between 1 and 10"))["text"]),
+                nu.print(nu.dict(Agent.ask("what number did you pick?"))["text"]),
+            ),
+        )
+        asyncio.run(nu.arun(app))
+    """
+
+    def __init__(self, *body: Nu) -> None:
+        super().__init__(_wrap_body(body))
+
+    @contextmanager
+    def _open(self, ctx: Context) -> Iterator[Context]:
+        yield ctx.bind(SessionHandle, SessionHandle())

nu/cluster/__init__.py

@@ -0,0 +1,45 @@
+"""nu.cluster - the ray compute fabric.
+
+Ray reframes as a compute fabric: locations are actor processes, addresses
+are tags, the interaction is ``Teleport`` (execute a Nu tree there).
+
+- ``RayCluster`` - the cluster handle FabricLifecycle. On asetup ensures
+  ray is initialized; on acleanup shuts down its own init (if any).
+- ``RayService`` - one remote actor hosting a Nu ``Context`` + tree
+  executor. Provisioned per-instance by ``Provide`` / ``ProvideList`` /
+  ``ProvideDict``.
+- ``RayClusterRef`` / ``RayServiceRef`` - fabric refs. ``RayServiceRef``
+  takes an arbitrary hashable tag (``RayServiceRef("ledger-main")``,
+  ``RayServiceRef(("ledger", 0))``).
+- ``Teleport`` - the interaction; ships the body term to a tagged
+  ``RayService`` and awaits its result.
+
+Typical shape::
+
+    Provide(RayCluster, {"address": "auto"},
+        ProvideList(RayService, [
+            {"actor_name": "worker-0", "num_cpus": 4},
+            {"actor_name": "worker-1", "num_cpus": 4},
+        ],
+            Sequential(
+                Teleport(some_tree, target=0),
+                Teleport(some_tree, target=1),
+            ),
+        ),
+    )
+"""
+
+from __future__ import annotations
+
+from .interactions import Teleport
+from .refs import RayClusterRef, RayServiceRef
+from .resources import RayCluster, RayService
+
+
+__all__ = [
+    "RayCluster",
+    "RayClusterRef",
+    "RayService",
+    "RayServiceRef",
+    "Teleport",
+]

nu/cluster/_actor.py

@@ -0,0 +1,122 @@
+"""``_RayServiceActor``: a ``@ray.remote`` host process for Nu execution.
+
+The actor holds a Nu ``Context`` and executes Nu trees against it. It is the
+in-actor half of a ``RayService`` - the ``RayService`` resource on the parent
+side spawns one of these actors, tells it to build its context, and later
+routes tree execution to it through ``aexecute``.
+
+An in-flight ``aexecute`` is tracked so shutdown can cancel and drain it
+before the actor tears down its context. This avoids a use-after-free when
+closing storage under a live query.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import TYPE_CHECKING
+
+import ray
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from nu.lang.runtime import Context
+    from nu.spans.bracket import _LifecycleBracket
+
+
+@ray.remote
+class _RayServiceActor:
+    """Ray actor hosting a Nu ``Context`` + tree executor.
+
+    Parent side (``RayService``) calls the async ``start`` / ``aexecute`` /
+    ``shutdown`` methods. The actor itself is stateless before ``start`` and
+    torn down after ``shutdown``.
+    """
+
+    def __init__(self) -> None:
+        self._ctx: Context | None = None
+        self._inflight: set[asyncio.Task] = set()
+        self._init_stack: contextlib.AsyncExitStack | None = None
+
+    async def start(
+        self,
+        init: _LifecycleBracket | None,
+        ctx_builder: Callable[[], Context | Awaitable[Context]] | None,
+    ) -> None:
+        """Build this actor's Context.
+
+        Prefers ``init`` (a lifecycle bracket): enters its ``_aopen`` on a
+        fresh ``Context()``, saves the resulting Context, and keeps the exit
+        stack open so the bracket's resources stay live until ``shutdown``.
+
+        Falls back to ``ctx_builder`` (a callable returning a Context or
+        awaitable). If both are ``None``, the actor gets a bare Context.
+        """
+        from nu.lang.runtime import Context
+
+        if init is not None:
+            stack = contextlib.AsyncExitStack()
+            await stack.__aenter__()
+            try:
+                self._ctx = await stack.enter_async_context(init._aopen(Context()))
+            except BaseException:
+                await stack.__aexit__(None, None, None)
+                raise
+            self._init_stack = stack
+            return
+        if ctx_builder is None:
+            self._ctx = Context()
+            return
+        result = ctx_builder()
+        if asyncio.iscoroutine(result):
+            result = await result
+        self._ctx = result
+
+    async def aexecute(self, tree: object, attrs: dict | None = None) -> object:
+        """Compile ``tree`` and evaluate it against this actor's Context.
+
+        Returns the root's value (``None`` for effect-only trees). ``attrs``
+        is merged into a shallow-copied Context before execution so the
+        parent's ``ctx.attrs`` can carry over without polluting the actor's
+        baseline.
+
+        Value-rooted trees (Query / Command / effectful Sequential) work
+        directly. A stream-rooted tree returns its async generator, which
+        won't cross the ray boundary; wrap it in a reducer or ``last()``
+        before ``Teleport``.
+        """
+        from nu.lang.helpers import aeval
+        from nu.lang.helpers import compile as compile_term
+
+        ctx = self._ctx
+        if attrs:
+            ctx = ctx._copy()
+            for key, value in attrs.items():
+                ctx.attrs[key] = value
+
+        task = asyncio.current_task()
+        if task is not None:
+            self._inflight.add(task)
+        try:
+            program = compile_term(tree)
+            value, _ = await aeval(program, ctx)
+            return value
+        finally:
+            if task is not None:
+                self._inflight.discard(task)
+
+    async def shutdown(self) -> None:
+        """Cancel in-flight executes, tear down init bracket, drop the Context."""
+        for t in list(self._inflight):
+            t.cancel()
+        for t in list(self._inflight):
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await t
+        self._inflight.clear()
+        if self._init_stack is not None:
+            with contextlib.suppress(Exception):
+                await self._init_stack.__aexit__(None, None, None)
+            self._init_stack = None
+        self._ctx = None