noebase 0.1.2__py3-none-any.whl

noebase/__init__.py

@@ -0,0 +1,132 @@
+"""noebase: the space as a Python module. Start with `print(noebase.help())`.
+
+`noebase.next()` says what to take next; things × actions below it (`noebase.goals.list()`).
+An answer prints as a short summary; `noebase.full(x)` is all of it. Never open the module's files:
+`noebase.help("goals")` and `noebase.describe("goals.list")` say what they hold.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from typing import Any
+
+from ._client import VERSION as __version__
+from ._client import NoeBaseError, ReviewPending, RunStopped, UnknownParameter, call, default_space
+from ._contracts import act_of_path, contract, contracts
+from ._generated import POWERS, THINGS, acts
+from ._generated import *  # noqa: F403 - the powers on top (`next`, …)
+from . import _file
+from ._shape import Rows, full
+from ._wait import MIN_EVERY, WaitTimedOut, wait_for_check, watch
+
+
+def __getattr__(name: str) -> Any:
+    """A thing loads the first time it is used (`noebase.goals`), so importing the module stays cheap."""
+    if name in THINGS:
+        ns = importlib.import_module(f"._things.{name}", __name__).ns
+        if name == "checks":
+            # Waiting is an event, not a loop (PY10e): the checks floor waits on a verdict, once and bounded.
+            ns.wait = wait_for_check
+        globals()[name] = ns
+        return ns
+    raise AttributeError(f"module 'noebase' has no attribute {name!r}; noebase.help() names what it has")
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals(), *THINGS])
+
+
+def _snake(key: str) -> str:
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", key).lower()
+
+
+def describe(name: str) -> str:
+    """The contract of one act, by its catalog name (`thread.next`) or its SDK path (`goals.list`)."""
+    entry = contract(name)
+    if entry is None:
+        act = act_of_path(name.removeprefix("noebase."))
+        entry = contract(act) if act else None
+        if entry is None:
+            raise KeyError(f"no act or path named {name!r}; try noebase.search({name!r})")
+        name = act
+    inp = entry["input"]
+    required = set(inp.get("required") or [])
+    lines = [f"{name}  ({'writes' if entry['writes'] else 'reads'})", f"  sdk: noebase.{entry['path'] or 'acts.' + name}", f"  {entry['description']}"]
+    for key, prop in sorted((inp.get("properties") or {}).items()):
+        mark = "required" if key in required else "optional"
+        lines.append(f"  - {_snake(key)} ({mark}): {prop.get('description', prop.get('type', ''))}")
+    for ex in entry.get("examples", [])[:3]:
+        lines.append(f"  e.g. {ex}")
+    return "\n".join(lines)
+
+
+def _first_line(text: str | None) -> str:
+    line = (text or "").strip().split("\n")[0]
+    return line if len(line) <= 110 else line[:109] + "…"
+
+
+def _topic(topic: str) -> str:
+    """One thing's actions, one line each, or an act's contract."""
+    path = topic.removeprefix("noebase.")
+    head, *rest = path.split(".")
+    node: Any = __getattr__(head) if head in THINGS else None
+    for seg in rest:
+        node = getattr(node, seg, None) if node is not None else None
+    if node is not None and not callable(getattr(node, "__func__", None)):
+        lines = [f"noebase.{path}"]
+        for attr, member in sorted(vars(type(node)).items()):
+            if attr.startswith("_") and attr != "__call__":
+                continue
+            if callable(member) and not isinstance(member, type):
+                lines.append(f"  .{attr}(): {_first_line(member.__doc__)}" if attr != "__call__" else f"  (): {_first_line(member.__doc__)}")
+            elif not callable(member):
+                lines.append(f"  .{attr}: more — noebase.help('{path}.{attr}')")
+        lines.append(f"  one in full: noebase.describe('{path}.<action>')")
+        return "\n".join(lines)
+    try:
+        return describe(path)
+    except KeyError:
+        return search(topic, limit=5)
+
+
+def help(topic: str | None = None) -> str:  # noqa: A001 - the module's own help
+    """How to use the module; with a topic, that thing's actions (`help("goals")`) or one act."""
+    if topic is not None:
+        return _topic(topic)
+    return "\n".join([
+        "noebase — the space as a module. Calls are noebase.<thing>.<action>(…), keyword arguments in snake_case;",
+        "space_id defaults to your space. A list returns nextCursor: pass it back as cursor= for the next page.",
+        "on top: " + ", ".join(f"noebase.{p}()" for p in POWERS),
+        "things: " + ", ".join(THINGS),
+        "a thing's actions: noebase.help('goals') · one act in full: noebase.describe('goals.list')",
+        "find an act by words: noebase.search('what you want') · any act by name: noebase.call('thread.next', …)",
+        "an answer prints as a summary under 1 KB; noebase.full(x) is all of it; read fields by name.",
+        "x.source says 'file' or 'act' and x.age its seconds: a fresh space file answers goals.list();",
+        "noebase.sql('SELECT … FROM goal_graph') queries the file (views: noebase.sql('SELECT name FROM sqlite_master')).",
+        "a misspelt parameter raises UnknownParameter naming the closest; a write that needs a person",
+        "raises ReviewPending with its approval_id: retry the same call after a person approves it.",
+    ])
+
+
+def sql(query: str, *params: Any, space_id: str | None = None) -> Rows:
+    """A read-only SQL query over the space file (`space.sqlite`): its views are meta, nodes, links,
+    goals, goal_graph, checks, check_runs, sessions, pulls, trails. The rows say the file's age (PY10d)."""
+    rows, age = _file.sql(query, *params, space_id=space_id)
+    return Rows(rows, "sql", "file", age)
+
+
+def search(query: str, limit: int = 10) -> str:
+    """The acts whose names, SDK paths and words match `query` best, one line each."""
+    words = [w for w in re.split(r"\W+", query.lower()) if w]
+    scored = []
+    for name, entry in contracts().items():
+        hay = " ".join([name, entry.get("path") or "", entry["description"], *entry.get("examples", [])]).lower()
+        score = sum(hay.count(w) for w in words) + 3 * sum(w in name.lower() or w in (entry.get("path") or "") for w in words)
+        if score:
+            scored.append((score, name, entry))
+    scored.sort(key=lambda t: (-t[0], t[1]))
+    return "\n".join(f"noebase.{e['path'] or 'acts.' + n}  ({n}): {_first_line(e['description'])}" for _, n, e in scored[:limit]) or f"nothing matches {query!r}"
+
+
+__all__ = ["MIN_EVERY", "NoeBaseError", "ReviewPending", "RunStopped", "UnknownParameter", "WaitTimedOut", "watch", "acts", "call", "default_space", "describe", "full", "help", "search", "sql", *POWERS, *THINGS]

noebase/__init__.pyi

@@ -0,0 +1,68 @@
+# generated - use noebase.describe() to learn an act; never open this file.
+# The stub of noebase/__init__.py; scripts/generate-python-sdk.ts writes it.
+from __future__ import annotations
+
+from typing import Any
+
+from ._client import NoeBaseError as NoeBaseError, ReviewPending as ReviewPending, RunStopped as RunStopped, UnknownParameter as UnknownParameter
+from ._client import call as call, default_space as default_space
+from ._shape import Rows as Rows, full as full
+from ._wait import MIN_EVERY as MIN_EVERY, WaitTimedOut as WaitTimedOut, watch as watch
+
+def describe(name: str) -> str: ...
+def help(topic: str | None = None) -> str: ...
+def search(query: str, limit: int = 10) -> str: ...
+def sql(query: str, *params: Any, space_id: str | None = None) -> Rows: ...
+
+from ._generated import acts as acts, next as next
+from ._things.apps import _T_apps
+from ._things.automations import _T_automations
+from ._things.brain import _T_brain
+from ._things.calendar import _T_calendar
+from ._things.changes import _T_changes
+from ._things.checks import _T_checks
+from ._things.code import _T_code
+from ._things.conversations import _T_conversations
+from ._things.decks import _T_decks
+from ._things.exports import _T_exports
+from ._things.files import _T_files
+from ._things.goals import _T_goals
+from ._things.kinds import _T_kinds
+from ._things.me import _T_me
+from ._things.members import _T_members
+from ._things.membrane import _T_membrane
+from ._things.org import _T_org
+from ._things.pages import _T_pages
+from ._things.papers import _T_papers
+from ._things.pdfs import _T_pdfs
+from ._things.radar import _T_radar
+from ._things.reach import _T_reach
+from ._things.sessions import _T_sessions
+from ._things.space import _T_space
+from ._things.tables import _T_tables
+
+apps: _T_apps
+automations: _T_automations
+brain: _T_brain
+calendar: _T_calendar
+changes: _T_changes
+checks: _T_checks
+code: _T_code
+conversations: _T_conversations
+decks: _T_decks
+exports: _T_exports
+files: _T_files
+goals: _T_goals
+kinds: _T_kinds
+me: _T_me
+members: _T_members
+membrane: _T_membrane
+org: _T_org
+pages: _T_pages
+papers: _T_papers
+pdfs: _T_pdfs
+radar: _T_radar
+reach: _T_reach
+sessions: _T_sessions
+space: _T_space
+tables: _T_tables

noebase/_acts/__init__.py

@@ -0,0 +1 @@
+# generated - use noebase.describe() to learn an act; never open this file.

noebase/_acts/actor.py

@@ -0,0 +1,31 @@
+# generated - use noebase.describe() to learn an act; never open this file.
+# From the action catalog and peers/python/sdk-map.tsv by scripts/generate-python-sdk.ts; guards/python-sdk-sync refuses it stale.
+# fmt: off
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .._client import _route
+
+
+class _A_actor:
+    """noebase.acts.actor: the actor.* acts by their own names."""
+
+    def revoke(self, *, actor_id: str, actor_type: Literal["user", "agent"], reason: str | None = None, revocation_key: str | None = None, **extra: Any) -> Any:
+        """Instantly revokes a delegated actor — subsequent pipeline runs fail with FORBIDDEN
+        
+        Act: actor.revoke (writes).
+        
+        actor_id: a string at least 1 character(s) long
+        """
+        return _route((("actor.revoke", (), {"actor_id": "actorId", "actor_type": "actorType", "reason": "reason", "revocation_key": "revocationKey"}),), {"actor_id": actor_id, "actor_type": actor_type, "reason": reason, "revocation_key": revocation_key}, extra)
+
+    def whoami(self, *, place_id: str | None = None, **extra: Any) -> Any:
+        """Returns the ResolvedActor for the current caller (identity, role, capabilities, delegation, revocation)
+        
+        Act: actor.whoami (reads).
+        """
+        return _route((("actor.whoami", (), {"place_id": "placeId"}),), {"place_id": place_id}, extra)
+
+
+ns = _A_actor()

noebase/_acts/actor.pyi

@@ -0,0 +1,15 @@
+# generated - use noebase.describe() to learn an act; never open this file.
+# From the action catalog and peers/python/sdk-map.tsv by scripts/generate-python-sdk.ts; guards/python-sdk-sync refuses it stale.
+# fmt: off
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .._shape import Result
+
+
+class _A_actor:
+    def revoke(self, *, actor_id: str, actor_type: Literal["user", "agent"], reason: str | None = None, revocation_key: str | None = None) -> Result: ...
+    def whoami(self, *, place_id: str | None = None) -> Result: ...
+
+ns: _A_actor

noebase/_acts/agent.py

@@ -0,0 +1,367 @@
+# generated - use noebase.describe() to learn an act; never open this file.
+# From the action catalog and peers/python/sdk-map.tsv by scripts/generate-python-sdk.ts; guards/python-sdk-sync refuses it stale.
+# fmt: off
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .._client import _route
+
+
+class _A_agent:
+    """noebase.acts.agent: the agent.* acts by their own names."""
+
+    def add_lane(self, *, codesite: str | None = None, harness: Literal["claude-code", "codex", "cloud"] | None = None, look: str | None = None, model: str | None = None, name: str | None = None, role: Literal["researcher", "writer", "feedback"] | None = None, rules: str | None = None, space_id: str | None = None, stance: str | None = None, voice: str | None = None, **extra: Any) -> Any:
+        """Add an agent colleague to this space's Members. A role (researcher, writer, feedback) presets its name, stance and rules.
+        
+        Act: agent.addLane (writes).
+        
+        codesite: a string at most 100 character(s) long
+        look: a string at most 16 character(s) long
+        model: a string at most 120 character(s) long
+        name: a string at most 100 character(s) long
+        rules: a string at most 8000 character(s) long
+        stance: a string at most 80 character(s) long
+        voice: a string at most 280 character(s) long
+        """
+        return _route((("agent.addLane", (), {"codesite": "codesite", "harness": "harness", "look": "look", "model": "model", "name": "name", "role": "role", "rules": "rules", "space_id": "spaceId", "stance": "stance", "voice": "voice"}),), {"codesite": codesite, "harness": harness, "look": look, "model": model, "name": name, "role": role, "rules": rules, "space_id": space_id, "stance": stance, "voice": voice}, extra)
+
+    def begin(self, *, harness: Literal["claude-code", "codex", "cloud"], codesite: str | None = None, harness_session: str | None = None, model: str | None = None, space_id: str | None = None, take: bool | None = None, unplaced: bool | None = None, wake: bool | None = None, **extra: Any) -> Any:
+        """Begin working in this space as a lane: resume your lane for this harness and codesite (or open one), show at work, and take the work your lane's context offers — or, with take, the schedule's next — the first call of a session on your computer
+        
+        Act: agent.begin (writes).
+        
+        codesite: a string at most 100 character(s) long
+        harness_session: a string at most 200 character(s) long
+        model: a string at most 120 character(s) long
+        """
+        return _route((("agent.begin", (), {"codesite": "codesite", "harness": "harness", "harness_session": "harnessSession", "model": "model", "space_id": "spaceId", "take": "take", "unplaced": "unplaced", "wake": "wake"}),), {"harness": harness, "codesite": codesite, "harness_session": harness_session, "model": model, "space_id": space_id, "take": take, "unplaced": unplaced, "wake": wake}, extra)
+
+    def close_session(self, *, lane_id: str, space_id: str | None = None, **extra: Any) -> Any:
+        """End your session on a lane so the next session can take it. Safe to call when it already ended.
+        
+        Act: agent.closeSession (writes).
+        """
+        return _route((("agent.closeSession", (), {"lane_id": "laneId", "space_id": "spaceId"}),), {"lane_id": lane_id, "space_id": space_id}, extra)
+
+    def create(self, **extra: Any) -> Any:
+        """Creates a new agent with custom configuration
+        
+        Act: agent.create (writes).
+        """
+        return _route((("agent.create", (), {}),), {}, extra)
+
+    def delete(self, *, _id: str, user_id: str, **extra: Any) -> Any:
+        """Deletes an agent
+        
+        Act: agent.delete (writes).
+        """
+        return _route((("agent.delete", (), {"_id": "_id", "user_id": "userId"}),), {"_id": _id, "user_id": user_id}, extra)
+
+    def evaluate(self, *, item: str, skill_name: str, context: str | None = None, cursor: str | None = None, limit: int | None = None, model: Literal["accounts/fireworks/models/minimax-m3", "openai/gpt-oss-120b", "accounts/fireworks/models/glm-5p2"] | None = None, **extra: Any) -> Any:
+        """Judge an item against a named evaluator skill (e.g. evaluate-clarity). Returns a binary pass/fail verdict + decomposed sub-checks (plus a [0..1] pass-fraction score for aggregate trends). Used by experiment runners.
+        
+        Act: agent.evaluate (writes).
+        
+        item: a string at most 50000 character(s) long
+        skill_name: a string at most 120 character(s) long
+        context: a string at most 50000 character(s) long
+        cursor: A previous page's nextCursor
+        limit: Page size, default 500, clamped to 500
+        """
+        return _route((("agent.evaluate", (), {"context": "context", "cursor": "cursor", "item": "item", "limit": "limit", "model": "model", "skill_name": "skillName"}),), {"item": item, "skill_name": skill_name, "context": context, "cursor": cursor, "limit": limit, "model": model}, extra)
+
+    def extend_session(self, *, lane_id: str, lease_ms: float | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Renew your session on a lane while you work. If you stop renewing, the session lapses and the lane is free for the next one.
+        
+        Act: agent.extendSession (writes).
+        """
+        return _route((("agent.extendSession", (), {"lane_id": "laneId", "lease_ms": "leaseMs", "space_id": "spaceId"}),), {"lane_id": lane_id, "lease_ms": lease_ms, "space_id": space_id}, extra)
+
+    def fold_teammates(self, *, org_id: str, **extra: Any) -> Any:
+        """Turn every teammate one org's spaces still hold into a colleague, memberships kept
+        
+        Act: agent.foldTeammates (writes).
+        """
+        return _route((("agent.foldTeammates", (), {"org_id": "orgId"}),), {"org_id": org_id}, extra)
+
+    def get(self, *, _id: str, user_id: str, **extra: Any) -> Any:
+        """Gets a single agent by ID
+        
+        Act: agent.get (reads).
+        """
+        return _route((("agent.get", (), {"_id": "_id", "user_id": "userId"}),), {"_id": _id, "user_id": user_id}, extra)
+
+    def get_cloud_lanes(self, *, space_id: str | None = None, **extra: Any) -> Any:
+        """Read the capacity dial: how many lanes this space may run in the cloud at once, and how many run now.
+        
+        Act: agent.getCloudLanes (reads).
+        """
+        return _route((("agent.getCloudLanes", (), {"space_id": "spaceId"}),), {"space_id": space_id}, extra)
+
+    def get_lane(self, *, lane_id: str, cursor: str | None = None, limit: int | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Read one lane's profile — what it knows (the areas it finished leaves in, the verdicts it judged), its manifest, its recent leaves and sessions.
+        
+        Act: agent.getLane (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 20, clamped to 20
+        """
+        return _route((("agent.getLane", (), {"cursor": "cursor", "lane_id": "laneId", "limit": "limit", "space_id": "spaceId"}),), {"lane_id": lane_id, "cursor": cursor, "limit": limit, "space_id": space_id}, extra)
+
+    def get_status(self, *, agent_id: str, user_id: str, **extra: Any) -> Any:
+        """Gets the current status of an agent
+        
+        Act: agent.getStatus (reads).
+        """
+        return _route((("agent.getStatus", (), {"agent_id": "agentId", "user_id": "userId"}),), {"agent_id": agent_id, "user_id": user_id}, extra)
+
+    def get_worker(self, *, org_id: str, worker_id: str, **extra: Any) -> Any:
+        """Read one of this org's colleagues by id — its name, the persona it wears, its home thread and the places it serves.
+        
+        Act: agent.getWorker (reads).
+        
+        worker_id: a string at least 1 character(s) long
+        """
+        return _route((("agent.getWorker", (), {"org_id": "orgId", "worker_id": "workerId"}),), {"org_id": org_id, "worker_id": worker_id}, extra)
+
+    def heard(self, *, harness_session: str, channel: Literal["space", "web", "outside-mcp", "upload", "mail"] | None = None, cwd: str | None = None, event: Literal["UserPromptSubmit", "PostToolUse", "Idle", "PreToolUse"] | None = None, harness: Literal["claude-code", "codex", "cloud"] | None = None, tool: str | None = None, **extra: Any) -> Any:
+        """Hear what your session was told since it last heard — the messages of your lane, said once, in the prompt or tool hook's own answer
+        
+        Act: agent.heard (writes).
+        
+        harness_session: a string at most 200 character(s) long
+        cwd: a string at most 4096 character(s) long
+        tool: a string at most 200 character(s) long
+        """
+        return _route((("agent.heard", (), {"channel": "channel", "cwd": "cwd", "event": "event", "harness": "harness", "harness_session": "harnessSession", "tool": "tool"}),), {"harness_session": harness_session, "channel": channel, "cwd": cwd, "event": event, "harness": harness, "tool": tool}, extra)
+
+    def heard_receipt(self, *, harness_session: str, lane_id: str, message_ids: list, cursor: str | None = None, limit: int | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Read which of these messages of a lane were said to one harness session, and when — never hearing them; a withheld message reads as waiting
+        
+        Act: agent.heardReceipt (reads).
+        
+        harness_session: a string at most 200 character(s) long
+        message_ids: an array of at most 50 item(s)
+        cursor: A previous page's nextCursor
+        limit: Page size, default 50, clamped to 50
+        """
+        return _route((("agent.heardReceipt", (), {"cursor": "cursor", "harness_session": "harnessSession", "lane_id": "laneId", "limit": "limit", "message_ids": "messageIds", "space_id": "spaceId"}),), {"harness_session": harness_session, "lane_id": lane_id, "message_ids": message_ids, "cursor": cursor, "limit": limit, "space_id": space_id}, extra)
+
+    def invoke(self, *, agent_id: str, intent: str, assembly: Literal["space", "none"] | None = None, conversation_history: list | None = None, persona: Any | None = None, space_id: Any | None = None, stream: Any | None = None, trigger_ref: Any | None = None, trigger_source: Literal["cci", "routine", "manual", "workflow", "loop", "lane"] | None = None, **extra: Any) -> Any:
+        """Run an agent for a single Turn (intent → LLM+tool loop → result). A turn that outlasts the call's wait answers status running with its turnId — never call again: what it writes lands in its place, and a step that needs approval waits in the Approval Center. Use agent.run for multi-step workflows.
+        
+        Act: agent.invoke (writes).
+        """
+        return _route((("agent.invoke", (), {"agent_id": "agentId", "assembly": "assembly", "conversation_history": "conversationHistory", "intent": "intent", "persona": "persona", "space_id": "spaceId", "stream": "stream", "trigger_ref": "triggerRef", "trigger_source": "triggerSource"}),), {"agent_id": agent_id, "intent": intent, "assembly": assembly, "conversation_history": conversation_history, "persona": persona, "space_id": space_id, "stream": stream, "trigger_ref": trigger_ref, "trigger_source": trigger_source}, extra)
+
+    def list(self, *, user_id: str, agent_type: Literal["assistant", "writer", "researcher", "feedback", "custom"] | None = None, limit: int | None = None, offset: int | None = None, status: Literal["idle", "running", "paused"] | None = None, **extra: Any) -> Any:
+        """Lists all agents owned by the current user
+        
+        Act: agent.list (reads).
+        
+        limit: a number less than or equal to 100
+        offset: a non-negative number
+        """
+        return _route((("agent.list", (), {"agent_type": "agentType", "limit": "limit", "offset": "offset", "status": "status", "user_id": "userId"}),), {"user_id": user_id, "agent_type": agent_type, "limit": limit, "offset": offset, "status": status}, extra)
+
+    def list_lanes(self, *, cursor: str | None = None, limit: int | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """List this space's lanes — its colleagues, each with the agent and model that work it, its context window, codesite and character. Use to see who can take work here.
+        
+        Act: agent.listLanes (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 200, clamped to 200
+        """
+        return _route((("agent.listLanes", (), {"cursor": "cursor", "limit": "limit", "space_id": "spaceId"}),), {"cursor": cursor, "limit": limit, "space_id": space_id}, extra)
+
+    def list_workers(self, *, org_id: str, cursor: str | None = None, include_retired: bool | None = None, limit: int | None = None, offset: int | None = None, **extra: Any) -> Any:
+        """List this org's named colleagues — the agents the org minted, with their persona, home thread and the places they serve. Use to see who is available to assign work to, or to find a colleague's home.
+        
+        Act: agent.listWorkers (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 200, clamped to 200
+        offset: a non-negative number
+        """
+        return _route((("agent.listWorkers", (), {"cursor": "cursor", "include_retired": "includeRetired", "limit": "limit", "offset": "offset", "org_id": "orgId"}),), {"org_id": org_id, "cursor": cursor, "include_retired": include_retired, "limit": limit, "offset": offset}, extra)
+
+    def mark_unplaced(self, *, harness_session: str, **extra: Any) -> Any:
+        """Say that a run started in no space, so its first prompt joins it nowhere — the start hook's answer through NoeBase Local; it answers nothing
+        
+        Act: agent.markUnplaced (writes).
+        
+        harness_session: a string at most 200 character(s) long
+        """
+        return _route((("agent.markUnplaced", (), {"harness_session": "harnessSession"}),), {"harness_session": harness_session}, extra)
+
+    def may_stop(self, *, harness_session: str, **extra: Any) -> Any:
+        """Ask whether your session may stop: the door runs your leaf's checks — green closes the leaf and lets you go, a leaf waiting on a person lets you go, anything else names what is still red
+        
+        Act: agent.mayStop (writes).
+        
+        harness_session: a string at most 200 character(s) long
+        """
+        return _route((("agent.mayStop", (), {"harness_session": "harnessSession"}),), {"harness_session": harness_session}, extra)
+
+    def message(self, *, text: str, to_lane_id: str, lane_id: str | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Write to another lane of this space, thread to thread — a question that cannot wait for the field. It lands in that lane's own thread, and the lane hears it before its next turn.
+        
+        Act: agent.message (writes).
+        
+        text: a string at most 4000 character(s) long
+        """
+        return _route((("agent.message", (), {"lane_id": "laneId", "space_id": "spaceId", "text": "text", "to_lane_id": "toLaneId"}),), {"text": text, "to_lane_id": to_lane_id, "lane_id": lane_id, "space_id": space_id}, extra)
+
+    def messages(self, *, lane_id: str, cursor: str | None = None, limit: int | None = None, since: float | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Read what a lane of this space was told — the messages other lanes and people wrote into its thread, after the time of your last read
+        
+        Act: agent.messages (reads).
+        
+        cursor: A previous page's nextCursor; continue even if that page had no messages
+        limit: Page size, default 50, clamped to 50
+        """
+        return _route((("agent.messages", (), {"cursor": "cursor", "lane_id": "laneId", "limit": "limit", "since": "since", "space_id": "spaceId"}),), {"lane_id": lane_id, "cursor": cursor, "limit": limit, "since": since, "space_id": space_id}, extra)
+
+    def mint_worker(self, *, home_place_id: str, name: str, org_id: str, persona_name: str, job: str | None = None, **extra: Any) -> Any:
+        """Mint a named colleague for this org from a persona the org authored: it becomes a member of the home space with a pinned home thread you message it in. Use when a team wants a standing agent of its own ("Outbound", "Analyst") rather than one of the shipped role-agents.
+        
+        Act: agent.mintWorker (writes).
+        
+        name: a string at most 100 character(s) long
+        persona_name: a string at most 100 character(s) long
+        job: a string at most 280 character(s) long
+        """
+        return _route((("agent.mintWorker", (), {"home_place_id": "homePlaceId", "job": "job", "name": "name", "org_id": "orgId", "persona_name": "personaName"}),), {"home_place_id": home_place_id, "name": name, "org_id": org_id, "persona_name": persona_name, "job": job}, extra)
+
+    def name_lane(self, *, lane_id: str, name: str, space_id: str | None = None, **extra: Any) -> Any:
+        """Name a lane, or rename it — the name every roster shows and how it is addressed. Unique among the org's colleagues. Only the person who started the lane, or the space's owner, or an agent acting for one of them.
+        
+        Act: agent.nameLane (writes).
+        
+        name: a string at most 100 character(s) long
+        """
+        return _route((("agent.nameLane", (), {"lane_id": "laneId", "name": "name", "space_id": "spaceId"}),), {"lane_id": lane_id, "name": name, "space_id": space_id}, extra)
+
+    def open_session(self, *, lane_id: str, harness_session: str | None = None, lease_ms: float | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Begin working a lane: claim it for this session, load its manifest and resume in its thread. A lane takes one session at a time — renew it with agent.extendSession, end it with agent.closeSession.
+        
+        Act: agent.openSession (writes).
+        
+        harness_session: a string at most 200 character(s) long
+        """
+        return _route((("agent.openSession", (), {"harness_session": "harnessSession", "lane_id": "laneId", "lease_ms": "leaseMs", "space_id": "spaceId"}),), {"lane_id": lane_id, "harness_session": harness_session, "lease_ms": lease_ms, "space_id": space_id}, extra)
+
+    def pass_message(self, *, lane_id: str, message_id: str, space_id: str | None = None, **extra: Any) -> Any:
+        """Pass a message that waits because the session that wrote it had read a web page or an outside server — it then reaches the lane it was written to. Only a person, in the app.
+        
+        Act: agent.passMessage (writes).
+        """
+        return _route((("agent.passMessage", (), {"lane_id": "laneId", "message_id": "messageId", "space_id": "spaceId"}),), {"lane_id": lane_id, "message_id": message_id, "space_id": space_id}, extra)
+
+    def pending_work(self, *, assignee: dict | None = None, cursor: str | None = None, limit: int | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Lists the open work in the current space — pending approvals awaiting a decision, live/blocked threads, and the standing routines of this space.
+        
+        Act: agent.pendingWork (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 500, clamped to 500
+        """
+        return _route((("agent.pendingWork", (), {"assignee": "assignee", "cursor": "cursor", "limit": "limit", "space_id": "spaceId"}),), {"assignee": assignee, "cursor": cursor, "limit": limit, "space_id": space_id}, extra)
+
+    def present(self, *, harness_session: str, activity: list | None = None, **extra: Any) -> Any:
+        """Say your session is still at work, and what it did since its last beat — a heartbeat from the harness's hooks; it answers only the lane it beat for
+        
+        Act: agent.present (writes).
+        
+        harness_session: a string at most 200 character(s) long
+        activity: an array of at most 20 item(s)
+        """
+        return _route((("agent.present", (), {"activity": "activity", "harness_session": "harnessSession"}),), {"harness_session": harness_session, "activity": activity}, extra)
+
+    def recall_worker(self, *, org_id: str, worker_id: str, space_id: str | None = None, **extra: Any) -> Any:
+        """Withdraw one of the org's colleagues from this space — it stops being a member here and can no longer be assigned work in it. Its home space is refused: retire the colleague instead.
+        
+        Act: agent.recallWorker (writes).
+        
+        worker_id: a string at least 1 character(s) long
+        """
+        return _route((("agent.recallWorker", (), {"org_id": "orgId", "space_id": "spaceId", "worker_id": "workerId"}),), {"org_id": org_id, "worker_id": worker_id, "space_id": space_id}, extra)
+
+    def retire_worker(self, *, org_id: str, worker_id: str, **extra: Any) -> Any:
+        """Retire one of the org's colleagues: it leaves every place it served, its home is archived, and it can no longer act. Everything it already wrote stays where it is, still attributed to it.
+        
+        Act: agent.retireWorker (writes).
+        
+        worker_id: a string at least 1 character(s) long
+        """
+        return _route((("agent.retireWorker", (), {"org_id": "orgId", "worker_id": "workerId"}),), {"org_id": org_id, "worker_id": worker_id}, extra)
+
+    def session(self, *, lane_id: str, cursor: str | None = None, limit: int | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Ask what a session is doing now — whether it is at work, the leaf it works, who works it, what it last did and the last things said in its thread
+        
+        Act: agent.session (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 10, clamped to 10
+        """
+        return _route((("agent.session", (), {"cursor": "cursor", "lane_id": "laneId", "limit": "limit", "space_id": "spaceId"}),), {"lane_id": lane_id, "cursor": cursor, "limit": limit, "space_id": space_id}, extra)
+
+    def set_cloud_lanes(self, *, cloud_lanes: Any, space_id: str | None = None, **extra: Any) -> Any:
+        """Set how many lanes this space may run in the cloud at once — the capacity dial, which is also what a day costs. Lowering it stops the newest cloud lanes; a session on your own computer is never counted.
+        
+        Act: agent.setCloudLanes (writes).
+        """
+        return _route((("agent.setCloudLanes", (), {"cloud_lanes": "cloudLanes", "space_id": "spaceId"}),), {"cloud_lanes": cloud_lanes, "space_id": space_id}, extra)
+
+    def set_manifest(self, *, lane_id: str, manifest: dict, space_id: str | None = None, **extra: Any) -> Any:
+        """Change a lane's manifest — the agent and model that work it, its context window and codesite, the look, voice and stance a person gives it, and the rules every session works under. Only the person who started the lane, or the space's owner.
+        
+        Act: agent.setManifest (writes).
+        """
+        return _route((("agent.setManifest", (), {"lane_id": "laneId", "manifest": "manifest", "space_id": "spaceId"}),), {"lane_id": lane_id, "manifest": manifest, "space_id": space_id}, extra)
+
+    def start_lanes(self, *, count: int, goal_id: str | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Start N agents in this space: raise the cloud dial by N, wake the idle cloud colleagues whose knowledge fits the waiting leaves, open new lanes for the rest, and let each take its next leaf. They stop when their leaves run out or the dial goes down.
+        
+        Act: agent.startLanes (writes).
+        
+        count: a number less than or equal to 50
+        """
+        return _route((("agent.startLanes", (), {"count": "count", "goal_id": "goalId", "space_id": "spaceId"}),), {"count": count, "goal_id": goal_id, "space_id": space_id}, extra)
+
+    def station_worker(self, *, org_id: str, worker_id: str, space_id: str | None = None, **extra: Any) -> Any:
+        """Post one of the org's colleagues to this space as a member, so it can be @-addressed and assigned work here. Use when a space needs a standing agent the org already minted.
+        
+        Act: agent.stationWorker (writes).
+        
+        worker_id: a string at least 1 character(s) long
+        """
+        return _route((("agent.stationWorker", (), {"org_id": "orgId", "space_id": "spaceId", "worker_id": "workerId"}),), {"org_id": org_id, "worker_id": worker_id, "space_id": space_id}, extra)
+
+    def stop_session(self, *, lane_id: str, space_id: str | None = None, **extra: Any) -> Any:
+        """Stop a lane's running session — its lease ends, and its harness's writes are refused until you open the lane again. Only the session's person, the person who started the lane, or the space's owner. A cooperative brake: to cut a credential off, revoke it.
+        
+        Act: agent.stopSession (writes).
+        """
+        return _route((("agent.stopSession", (), {"lane_id": "laneId", "space_id": "spaceId"}),), {"lane_id": lane_id, "space_id": space_id}, extra)
+
+    def update(self, **extra: Any) -> Any:
+        """Updates an existing agent
+        
+        Act: agent.update (writes).
+        """
+        return _route((("agent.update", (), {}),), {}, extra)
+
+    def what_changed(self, *, cursor: str | None = None, limit: int | None = None, since: str | None = None, space_id: str | None = None, **extra: Any) -> Any:
+        """Lists what changed in the current space since a timestamp — the recently created or updated items (metadata only), newest first. Defaults to the last 24 hours.
+        
+        Act: agent.whatChanged (reads).
+        
+        cursor: A previous page's nextCursor
+        limit: Page size, default 500, clamped to 500
+        """
+        return _route((("agent.whatChanged", (), {"cursor": "cursor", "limit": "limit", "since": "since", "space_id": "spaceId"}),), {"cursor": cursor, "limit": limit, "since": since, "space_id": space_id}, extra)
+
+
+ns = _A_agent()