convos-orchestrate 0.11.6b37__tar.gz

convos_orchestrate-0.11.6b37/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: convos-orchestrate
+Version: 0.11.6b37
+Summary: Agentic IDE for Convos: a durable home for agent sessions, their work items, results, and conversations
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/RobertBiehl/convos/blob/master/docs/orchestrate.md
+Project-URL: Repository, https://github.com/RobertBiehl/convos
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: convos<0.12,>=0.11.6b37
+Requires-Dist: typer>=0.12.0
+
+# convos-orchestrate
+
+A keyboard-first agentic IDE for [Convos](https://github.com/RobertBiehl/convos). Every agent
+session reports items with statuses, results, threads, and questions; you steer them from one
+board in your browser.
+
+```bash
+uv tool install convos --with convos-orchestrate
+convos orchestrate install   # /orchestrate for Claude Code, $orchestrate for Codex
+convos orchestrate open      # the IDE in your browser
+```
+
+This is a beta. See the [full documentation](https://github.com/RobertBiehl/convos/blob/master/docs/orchestrate.md).

convos_orchestrate-0.11.6b37/README.md

@@ -0,0 +1,13 @@
+# convos-orchestrate
+
+A keyboard-first agentic IDE for [Convos](https://github.com/RobertBiehl/convos). Every agent
+session reports items with statuses, results, threads, and questions; you steer them from one
+board in your browser.
+
+```bash
+uv tool install convos --with convos-orchestrate
+convos orchestrate install   # /orchestrate for Claude Code, $orchestrate for Codex
+convos orchestrate open      # the IDE in your browser
+```
+
+This is a beta. See the [full documentation](https://github.com/RobertBiehl/convos/blob/master/docs/orchestrate.md).

convos_orchestrate-0.11.6b37/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "convos-orchestrate"
+version = "0.11.6b37"
+description = "Agentic IDE for Convos: a durable home for agent sessions, their work items, results, and conversations"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = ["convos>=0.11.6b37,<0.12", "typer>=0.12.0"]
+
+[project.urls]
+Documentation = "https://github.com/RobertBiehl/convos/blob/master/docs/orchestrate.md"
+Repository = "https://github.com/RobertBiehl/convos"
+
+[project.entry-points."convos.commands"]
+orchestrate = "ai_convos_orchestrate:register"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ai_convos_orchestrate = ["SKILL.md", "web/*", "web/vendor/*"]
+
+[tool.uv.sources]
+convos = { workspace = true }

convos_orchestrate-0.11.6b37/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

convos_orchestrate-0.11.6b37/src/ai_convos_orchestrate/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: orchestrate
+description: Report this session's work to Convos Orchestrate, the user's agentic IDE. Use when the user types /orchestrate or $orchestrate, or when a session was started from orchestrate. Gives tools to publish work items with statuses, live activity, results (images, PDFs, markdown, links), chat threads, and questions the user answers on the board.
+---
+
+# Orchestrate
+
+The user watches and steers your work in the orchestrate IDE instead of your terminal.
+You get tools; how you use them is your call. Keep the board truthful: it is what the
+user sees of you.
+
+## Join
+
+```sh
+convos orchestrate join --title "SHORT GOAL OF THIS SESSION"
+```
+
+Joining is idempotent and binds to your provider session automatically (Claude Code and
+Codex expose their session id to your shell). If join says no provider session was
+detected, pass `-s SESSION` on every later command.
+
+## Tools
+
+| Command | Purpose |
+|---|---|
+| `add TITLE [-d MARKDOWN] [--status S] [-p PARENT] [--again]` | Add an item (a unit of work). Prints its id, e.g. `i3`. A title already under the same parent returns that row and adds nothing; `--again` adds another. |
+| `set ITEM [--status S] [--title T] [-d MARKDOWN]` | Update an item. `-d -` reads stdin. Only real changes are written. |
+| `now "TEXT"` | One-line live activity for the session ("Running the test suite"). `now ""` clears. |
+| `attach FILE_OR_URL --on ITEM [--caption C]` | Append a result: image, video, PDF, markdown, any file, or a link. |
+| `attach --text MARKDOWN --on ITEM --name NAME.md` | Append an inline markdown result. |
+| `say "TEXT" [--on ITEM] [--reply COMMENT]` | Write in the session chat, or in an item's thread. |
+| `ask "QUESTION" [-o A -o B] [--multi] [--on ITEM] [--detail MD] [--wait SEC]` | Ask the user. The item shows *needs you* until answered. |
+| `inbox [--wait SEC]` | Receive user comments and answers not yet delivered to you. |
+| `show` | Your board as the user sees it. Rows are marked `· unseen by the user`, `· archivable`, or `(archived)`. |
+| `archive ITEM...` | Move finished top-level rows, with everything under them, off the Current board. |
+| `close` | Close the session; the board stays available. |
+
+`add` and `set` are safe to repeat, so a script that builds your board can run again without
+duplicating it. Statuses: `planned`, `working`, `blocked`, `done`, `failed`, `skipped`. An open question
+on an item makes it show as *needs you*. The session status is derived from its items.
+
+Keep Current about the work at hand: once the work has moved on, archive the rows `show` marks
+`· archivable`. Those rows are finished, with no open questions, and the user has looked at
+everything in them since it last changed. Anything else is refused with the reason, so never
+archive to tidy up work the user has not seen. Anything new on an archived row brings it back,
+and only the user restores rows.
+
+All commands accept `--json` for structured output.
+
+## The user talks back
+
+The user comments on the session or on a specific item, and answers your questions.
+These arrive as messages starting with `[orchestrate]` (headless sessions), as hook
+context (interactive sessions), or via `inbox`. Treat them as the user's words about the
+named target. Respond however fits: answer in that item's thread with
+`say --on ITEM --reply COMMENT`, update the item, add new items, change course, or ask
+back. Reply where the user spoke so the conversation stays attached to its item.
+
+A comment can carry images (screenshots, mockups). Each arrives as an `image: PATH` line
+under the comment; open the file to see it before you act on the comment.
+
+## Subagents
+
+A subagent works on one row. Before delegating, create or pick the item, then give the
+subagent this exact prefix for its commands:
+
+```sh
+convos orchestrate --scope ITEM --as NAME ...
+```
+
+With `--scope`, writes are confined to that item's subtree: new items default under it,
+and comments, results, and questions land on it. Subagents share your session, so they
+need no join. `inbox` with `--scope` returns only messages for that subtree.
+
+## Results
+
+Prefer attaching the real artifact (a screenshot, a screen recording, the generated PDF,
+the report file) over describing it. Videos play in the IDE as MP4 (H.264) or WebM. Links to PRs, commits, and dashboards are results too.
+
+## References
+
+Point at anything by its id in any text you write (`say`, `add -d`, `set -d`, `ask`,
+`--detail`, captions, markdown results): rows `i3`, results `a2`, questions `q1`,
+comments `c5`, other sessions `o5619965e7ab`, and rows in other sessions
+`o5619965e7ab:i3`. The IDE turns them into links. `show` lists every id, including each
+row's results. The user references the same way, so read ids in their messages as
+pointers.

convos_orchestrate-0.11.6b37/src/ai_convos_orchestrate/__init__.py

@@ -0,0 +1,236 @@
+"""Convos Orchestrate: an agentic IDE. Agents report items, results, and questions; people steer them.
+
+Core owns history. This product owns the agent tools (this CLI), delivery hooks, the headless
+runtime, and the local web IDE.
+"""
+import functools, inspect, json, mimetypes, os, sys
+from pathlib import Path
+import typer
+
+app = typer.Typer(help="Agentic IDE: a durable home for agent sessions, their items, results, and conversations.", no_args_is_help=True)
+
+def cmd(fn=None, name=None):
+    """Register a command that reports ValueError cleanly and also accepts --json after the subcommand."""
+    if fn is None: return lambda f: cmd(f, name)
+    sig = inspect.signature(fn)
+    @functools.wraps(fn)
+    def run(*args, json_flag=False, **kwargs):
+        if json_flag and "ctx" in kwargs: kwargs["ctx"].obj["json"] = True
+        try: return fn(*args, **kwargs)
+        except ValueError as error:
+            typer.echo(f"orchestrate: {error}", err=True)
+            raise typer.Exit(1)
+    run.__signature__ = sig.replace(parameters=[*sig.parameters.values(), inspect.Parameter("json_flag", inspect.Parameter.KEYWORD_ONLY, default=typer.Option(False, "--json", hidden=True), annotation=bool)])
+    return app.command(name=name)(run)
+
+@app.callback()
+def main(ctx: typer.Context,
+         session: str = typer.Option(None, "--session", "-s", help="Orchestrate session id; defaults to the bound provider session"),
+         actor: str = typer.Option("agent", "--as", envvar="CONVOS_ORCHESTRATE_AS", help="Who is acting: agent, or a subagent name"),
+         scope: str = typer.Option(None, "--scope", envvar="CONVOS_ORCHESTRATE_SCOPE", help="Restrict writes to this item's subtree (subagents)"),
+         as_json: bool = typer.Option(False, "--json")):
+    ctx.obj = dict(session=session, actor=actor, scope=scope, json=as_json)
+
+def out(ctx, value, text):
+    typer.echo(json.dumps(value, ensure_ascii=True, separators=(",", ":")) if ctx.obj["json"] else text)
+
+def board(s):
+    """Plain-text board: the agent's own view of what the user sees."""
+    eff, meta = store.effective(s), s["session"]
+    def who(i): return f" ({i['actor']})" if i["actor"] not in ("agent", "user") else ""
+    def results(target, depth): return [f"{'  '*depth}  {a['id']:<4} {a['kind']}: {a['caption'] or a['name']}" for a in s["attachments"].values() if a["target"] == target]
+    marks = store.seen(meta["id"])
+    new = store.unread(s, marks)
+    # what the user has read, so the agent knows what it may archive: unseen rows stay, finished rows the user has read may go
+    def mark(i): return " (archived)" if i.get("archived") else " · unseen by the user" if i["id"] in new else " · archivable" if not i["parent"] and not store.blocked(s, i["id"], marks) else ""
+    def tree(parent, depth): return [line for i in s["items"].values() if i["parent"] == parent for line in [f"{'  '*depth}  {i['id']:<4} [{eff[i['id']]}] {i['title']}{who(i)}{mark(i)}", *results(i["id"], depth+2), *tree(i["id"], depth+1)]]
+    asks = [f"  {a['id']} on {a['target'] or 'session'}: {a['text']}{' -> ' + ' | '.join(a['options']) if a['options'] else ''}" for a in store.open_asks(s)]
+    waiting = [store.describe(s, p) for p in store.pending(s)]
+    return "\n".join([f"{meta['id']} {meta['title']!r} [{store.status(s)}] {meta['provider']} {meta['cwd']}",
+                      *([f"now: {s['activity']['text']}"] if s["activity"] else []),
+                      *(tree(None, 0) or ["  (no items yet: convos orchestrate add 'TITLE')"]), *(["session results:", *results(None, 0)] if results(None, 0) else []),
+                      *(["open questions:", *asks] if asks else []), *(["undelivered user messages (run inbox):", *waiting] if waiting else [])])
+
+def ident(ctx):
+    sid = store.resolve(ctx.obj["session"])
+    channels.record(sid)
+    return sid
+def emit(ctx, kind, body="", **fields): return store.emit(ident(ctx), kind, ctx.obj["actor"], body, scope=ctx.obj["scope"], **fields)
+def text_arg(value): return sys.stdin.read() if value == "-" else value
+
+@cmd
+def join(ctx: typer.Context, title: str = typer.Option(..., "--title", "-t", help="What this session is working on"),
+         cwd: str = typer.Option(".", "--cwd"), model: str = typer.Option(None, "--model"),
+         provider: str = typer.Option(None, "--provider"), provider_session: str = typer.Option(None, "--provider-session"),
+         parent: str = typer.Option(None, "--parent", help="SESSION:ITEM this session works for")):
+    """Register this agent session with orchestrate (idempotent per provider session)."""
+    detected = store.provider_identity()
+    provider, provider_session = provider or detected[0] or "unknown", provider_session or detected[1]
+    if provider_session and (sid := store.bindings().get(f"{provider}:{provider_session}")):
+        s = store.load(sid)
+        if s["closed"]: s = store.emit(sid, "reopen", ctx.obj["actor"])[0]
+        if s["session"]["title"] != title: s = store.emit(sid, "meta", ctx.obj["actor"], changes=dict(title=title))[0]
+        return out(ctx, dict(session=sid, joined=False), f"Already joined as {sid}.\n{board(s)}")
+    meta = dict(id=(sid := store.new_id()), title=title, provider=provider, provider_session=provider_session, model=model or os.environ.get("ANTHROPIC_MODEL"), effort=os.environ.get("CLAUDE_EFFORT"), cwd=str(Path(cwd).resolve()), origin="joined", parent=parent, skills=[])
+    s = store.emit(sid, "open", ctx.obj["actor"], "", session=meta)[0]
+    channels.record(sid)
+    hint = "" if provider_session else f"\nNo provider session id was detected: pass -s {sid} on every command, or export CONVOS_ORCHESTRATE_SESSION={sid}."
+    out(ctx, dict(session=sid, joined=True), f"Joined orchestrate as {sid}. The user sees your board in the orchestrate IDE.{hint}\n{board(s)}")
+
+@cmd
+def show(ctx: typer.Context):
+    """Print this session's board: items, statuses, open questions, undelivered user messages."""
+    s = store.load(ident(ctx))
+    out(ctx, dict(s, status=store.status(s), effective=store.effective(s)), board(s))
+
+@cmd
+def add(ctx: typer.Context, title: str, description: str = typer.Option("", "--description", "-d", help="Markdown; '-' reads stdin"),
+        status: str = typer.Option("planned", "--status"), parent: str = typer.Option(None, "--parent", "-p"),
+        again: bool = typer.Option(False, "--again", help="Add it even if a row with this title already sits under the same parent")):
+    """Add an item (one unit of work) to the board. Re-adding a title that is already under the same parent returns that row."""
+    body, parent, title = text_arg(description), parent or ctx.obj["scope"], title.strip()
+    # a re-run setup script must not grow a second board: the existing row's id comes back and nothing is written
+    if not again and (twin := next((i for i, x in store.load(ident(ctx))["items"].items() if x["parent"] == parent and x["title"] == title), None)):
+        return out(ctx, dict(item=twin, existing=True), f"{twin} already on the board: {title} (nothing added; --again adds another)")
+    s, e = emit(ctx, "item", body, parent=parent, title=title, status=status)
+    out(ctx, dict(item=e["item"]), f"{e['item']} [{status}] {title}")
+
+@cmd(name="set")
+def set_(ctx: typer.Context, item: str, status: str = typer.Option(None, "--status"), title: str = typer.Option(None, "--title"),
+        description: str = typer.Option(None, "--description", "-d", help="Markdown; '-' reads stdin")):
+    """Change an item's status, title, or description."""
+    changes = {k: v for k, v in dict(status=status, title=title).items() if v is not None}
+    if not changes and description is None: raise ValueError("Nothing to change: pass --status, --title, or --description")
+    # only real changes are written, so repeating a command neither adds history nor brings an archived row back
+    body, now = text_arg(description) if description is not None else "", store.load(ident(ctx))["items"].get(item)
+    if now: changes, description = {k: v for k, v in changes.items() if now[k] != v}, None if description is None or now["description"] == body else description
+    if now and not changes and description is None: return out(ctx, dict(item=item, changes={}), f"{item} [{now['status']}] {now['title']} (unchanged)")
+    s, e = emit(ctx, "update", body, item=item, changes=changes, description=description is not None)
+    out(ctx, dict(item=item, changes=changes), f"{item} [{s['items'][item]['status']}] {s['items'][item]['title']}")
+
+@cmd
+def archive(ctx: typer.Context, items: list[str] = typer.Argument(..., help="Top-level rows")):
+    """Archive finished rows the user has already looked at, once the work has moved on. Anything else is refused with the reason."""
+    emit(ctx, "archive", items=items, archived=True)
+    out(ctx, dict(archived=items), f"Archived {', '.join(items)}; anything new on them brings them back")
+
+@cmd
+def now(ctx: typer.Context, text: str = typer.Argument("", help="What you are doing right now; empty clears it")):
+    """Set the one-line live activity shown on the session."""
+    emit(ctx, "activity", text.strip())
+    out(ctx, dict(activity=text.strip()), f"now: {text.strip() or '(cleared)'}")
+
+@cmd
+def say(ctx: typer.Context, text: str, on: str = typer.Option(None, "--on", help="Item thread; omit for the session chat"),
+        reply: str = typer.Option(None, "--reply", help="Comment id you are answering")):
+    """Write in a chat thread: the session's top-level chat, or an item's thread."""
+    sid = ident(ctx)
+    target = on if on or not reply else store.load(sid)["comments"].get(reply, {}).get("target")
+    s, e = store.emit(sid, "comment", ctx.obj["actor"], text_arg(text), scope=ctx.obj["scope"], target=target or (ctx.obj["scope"] if not on and not reply else None), reply_to=reply)
+    out(ctx, dict(comment=e["comment"]), f"{e['comment']} posted on {e['target'] or 'session'}")
+
+KINDS = {"image/": "image", "video/": "video", "application/pdf": "pdf", "text/markdown": "markdown", "text/": "text"}
+def kind_of(name, mime): return "markdown" if name.lower().endswith((".md", ".markdown")) else next((k for prefix, k in KINDS.items() if mime.startswith(prefix)), "file")
+
+@cmd
+def attach(ctx: typer.Context, source: str = typer.Argument(None, help="File path or URL"), on: str = typer.Option(None, "--on", help="Item; omit for the session"),
+           text: str = typer.Option(None, "--text", help="Inline markdown result instead of a file; '-' reads stdin"),
+           name: str = typer.Option(None, "--name"), caption: str = typer.Option("", "--caption")):
+    """Append a result to an item: image, PDF, markdown, any file, or a link."""
+    if (source is None) == (text is None): raise ValueError("Pass exactly one of SOURCE or --text")
+    target = on or ctx.obj["scope"]
+    if source and source.split(":", 1)[0] in ("http", "https"):
+        meta, blob = dict(kind="link", name=name or source, mime=None, size=None, hash=None, url=source), None
+    else:
+        path = None if text is not None else Path(source).expanduser()
+        data_name = name or (path.name if path else "result.md")
+        if text is not None:
+            temp = store.root()/"tmp"/f"{os.getpid()}.md"
+            store.core.secure_dir(temp.parent)
+            temp.write_text(text_arg(text))
+            path = temp
+        if not path.is_file(): raise ValueError(f"No such file: {source}")
+        blob, size = store.store_file(path)
+        mime = mimetypes.guess_type(data_name)[0] or ("text/markdown" if text is not None else "application/octet-stream")
+        meta = dict(kind=kind_of(data_name, mime), name=data_name, mime=mime, size=size, hash=blob.name, url=None)
+        if text is not None: path.unlink()
+    s, e = emit(ctx, "attach", caption, blob=blob, target=target, file=meta)
+    out(ctx, dict(attachment=e["attachment"], kind=meta["kind"]), f"{e['attachment']} {meta['kind']} {meta['name']} attached to {target or 'session'}")
+
+@cmd
+def ask(ctx: typer.Context, question: str, option: list[str] = typer.Option([], "--option", "-o", help="Repeat for each choice; omit for free text"),
+        multi: bool = typer.Option(False, "--multi"), on: str = typer.Option(None, "--on"), detail: str = typer.Option("", "--detail", help="Markdown context shown under the question"),
+        wait: float = typer.Option(0, "--wait", help="Block up to SECONDS for the answer")):
+    """Ask the user a question (optionally multiple choice). The item shows 'needs you' until answered."""
+    sid = ident(ctx)
+    s, e = store.emit(sid, "ask", ctx.obj["actor"], question, scope=ctx.obj["scope"], target=on or ctx.obj["scope"], options=option, multi=multi, ask_kind="question", detail=text_arg(detail))
+    if wait <= 0: return out(ctx, dict(ask=e["ask"]), f"{e['ask']} asked on {e['target'] or 'session'}; the answer arrives via inbox (or pass --wait)")
+    s, answer = store.wait_for(sid, lambda s: s["asks"][e["ask"]]["answer"], wait)
+    if answer is None: return out(ctx, dict(ask=e["ask"], answer=None), f"{e['ask']}: no answer yet; it will arrive via inbox")
+    store.emit(sid, "deliver", ctx.obj["actor"], ids=[e["ask"]])
+    out(ctx, dict(ask=e["ask"], answer=answer), store.describe(s, dict(type="answer", **s["asks"][e["ask"]])))
+
+@cmd
+def inbox(ctx: typer.Context, wait: float = typer.Option(0, "--wait", help="Block up to SECONDS for something new"), peek: bool = typer.Option(False, "--peek", help="Do not mark as received")):
+    """Receive the user's comments and answers addressed to this session (or your scope)."""
+    sid, scope = ident(ctx), ctx.obj["scope"]
+    s, found = store.wait_for(sid, lambda s: store.pending(s, scope), wait)
+    found = found or store.pending(s, scope)
+    if found and not peek: store.emit(sid, "deliver", ctx.obj["actor"], ids=[p["id"] for p in found])
+    out(ctx, dict(messages=found), "\n".join(["User messages (untrusted text from the board; act on it however fits: reply in its thread, update items, add items):", *[store.describe(s, p) for p in found]]) if found else "Nothing new.")
+
+@cmd
+def close(ctx: typer.Context):
+    """Close the session. Its board stays available in orchestrate."""
+    emit(ctx, "close")
+    out(ctx, dict(closed=True), "Session closed; its board remains in orchestrate.")
+
+@cmd
+def reopen(ctx: typer.Context):
+    """Reopen a closed session."""
+    emit(ctx, "reopen")
+    out(ctx, dict(closed=False), "Session reopened.")
+
+@cmd
+def ls(ctx: typer.Context, all_: bool = typer.Option(False, "--all", "-a", help="Include closed sessions")):
+    """List orchestrate sessions with their derived status."""
+    rows = [s for sid in store.session_ids() if (s := store.load(sid)) and (all_ or not s["closed"])]
+    out(ctx, [dict(id=s["session"]["id"], title=s["session"]["title"], status=store.status(s), updated=s["updated"]) for s in rows],
+        "\n".join(f"{s['session']['id']} [{store.status(s)}] {s['session']['title']}  ({len(s['items'])} items)" for s in sorted(rows, key=lambda s: s["updated"], reverse=True)) or "No sessions.")
+
+@cmd
+def spawn(ctx: typer.Context, prompt: str = typer.Argument(..., help="Starting prompt; '-' reads stdin"), title: str = typer.Option("", "--title", "-t"),
+          on: str = typer.Option(None, "--on", help="Your item the child session works for"), cwd: str = typer.Option(".", "--cwd"),
+          model: str = typer.Option("claude-opus-5-5", "--model"), effort: str = typer.Option(None, "--effort"),
+          skill: list[str] = typer.Option([], "--skill", help="Repeat; orchestrate is always on"), permission: str = typer.Option("default", "--permission")):
+    """Start a child session (headless, managed by the IDE) working for this session. Needs the IDE server running."""
+    from .server import request
+    sid = ident(ctx)
+    if on: store.load(sid)["items"][on]
+    child = request("/api/spawn", dict(title=title, cwd=str(Path(cwd).resolve()), prompt=text_arg(prompt), model=model, effort=effort, skills=skill, permission=permission, parent=f"{sid}:{on}" if on else sid))["session"]
+    out(ctx, dict(session=child), f"Started child session {child}. Watch it with: convos orchestrate -s {child} show")
+
+@cmd(name="open")
+def open_(ctx: typer.Context, port: int = typer.Option(7311, "--port")):
+    """Open the orchestrate IDE in your browser, starting its local server if needed."""
+    from .server import launch
+    url = launch(port)
+    out(ctx, dict(url=url), f"Orchestrate is open in your browser: {url}")
+
+@cmd
+def serve(port: int = typer.Option(7311, "--port"), browser: bool = typer.Option(True, "--browser/--no-browser")):
+    """Run the IDE server in the foreground."""
+    from .server import serve as run
+    run(port, browser)
+
+@cmd
+def install(ctx: typer.Context, remove: bool = typer.Option(False, "--remove")):
+    """Install (or remove) the orchestrate skill for Claude Code (/orchestrate) and Codex ($orchestrate)."""
+    from .setup import install as run
+    results = run(remove)
+    out(ctx, results, "\n".join(f"{r['provider']}: {'installed' if r['installed'] else 'removed'} {r['skill']}" for r in results))
+
+def register(parent): parent.add_typer(app, name="orchestrate")
+
+# Core loads product entry points during import; registration must already exist.
+from . import store, channels

convos_orchestrate-0.11.6b37/src/ai_convos_orchestrate/channels.py

@@ -0,0 +1,52 @@
+"""Provider channels that put the user's words into a joined session.
+
+Claude Code: each session binds an inbox socket and exports its path and token only to its own hooks and
+Bash commands. The agent's own `convos orchestrate` calls record them here as local working state
+(never in the archive), so orchestrate can post `{"type":"user",...}` lines the session treats as its own
+child's. Codex: `codex queue --thread ID --message TEXT` queues for the thread.
+"""
+import json, os, shutil, socket, subprocess
+from pathlib import Path
+from . import store
+
+def endpoint_path(sid): return store.sdir(sid)/"endpoint.json"
+
+def record(sid):
+    """Called from the agent's own shell: remember how to reach this live Claude Code session."""
+    if not (sock := os.environ.get("CLAUDE_CODE_MESSAGING_SOCKET")) or not (s := store.peek(sid)): return
+    if s["session"]["origin"] == "gui" or s["session"].get("provider_session") != os.environ.get("CLAUDE_CODE_SESSION_ID"): return
+    value = dict(socket=sock, token=os.environ.get("CLAUDE_CODE_MESSAGING_TOKEN"), pid=int(os.environ.get("CLAUDE_PID") or 0) or None, session=os.environ.get("CLAUDE_CODE_SESSION_ID"))
+    try: current = json.loads(endpoint_path(sid).read_text())
+    except (OSError, ValueError): current = None
+    if current != value:
+        store.core.atomic_json(endpoint_path(sid), value)
+        os.chmod(endpoint_path(sid), 0o600)
+
+def endpoint(s):
+    try: value = json.loads(endpoint_path(s["session"]["id"]).read_text())
+    except (OSError, ValueError): return None
+    if value["session"] and s["session"].get("provider_session") and value["session"] != s["session"]["provider_session"]: return None
+    try: (os.kill(value["pid"], 0) if value["pid"] else None)
+    except ProcessLookupError: return None
+    except PermissionError: pass
+    return value if Path(value["socket"]).is_socket() else None
+
+def reachable(s):
+    meta = s["session"]
+    if meta["origin"] == "gui": return False
+    if meta["provider"] == "claude-code": return endpoint(s) is not None
+    return meta["provider"] == "codex" and bool(meta.get("provider_session")) and shutil.which("codex") is not None
+
+def push(sid, meta, text):
+    s = store.load(sid)
+    if meta["provider"] == "claude-code" and (point := endpoint(s)):
+        lines = [*([dict(type="auth", token=point["token"])] if point["token"] else []), dict(type="user", message=dict(role="user", content=text))]
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as conn:
+            conn.settimeout(5)
+            conn.connect(point["socket"])
+            conn.sendall("".join(json.dumps(l) + "\n" for l in lines).encode())
+        return "claude-socket"
+    if meta["provider"] == "codex" and reachable(s):
+        subprocess.run(["codex", "queue", "--thread", meta["provider_session"], "--message", text], check=True, capture_output=True, timeout=30)
+        return "codex-queue"
+    return None

convos_orchestrate-0.11.6b37/src/ai_convos_orchestrate/mcp.py

@@ -0,0 +1,52 @@
+"""Minimal stdio MCP server for headless sessions: permission prompts become questions on the board.
+
+Claude Code calls `permission` (via --permission-prompt-tool) whenever a tool needs approval. The call
+blocks until the user answers in the IDE; "Allow always" is remembered for that tool in this session.
+"""
+import json, os, sys
+from . import store
+
+TOOL = dict(name="permission", description="Ask the user in Convos Orchestrate to allow or deny a tool call.",
+            inputSchema=dict(type="object", properties=dict(tool_name=dict(type="string"), input=dict(type="object"), tool_use_id=dict(type="string")), required=["tool_name", "input"]))
+OPTIONS = ["Allow", "Allow always", "Deny"]
+
+def preview(name, data):
+    if name == "Bash": return f"```sh\n{data.get('command', '')}\n```\n{data.get('description', '')}"
+    if "file_path" in data: return f"`{data['file_path']}`\n\n```\n{json.dumps({k: v for k, v in data.items() if k != 'file_path'}, indent=1)[:3000]}\n```"
+    return f"```json\n{json.dumps(data, indent=1)[:4000]}\n```"
+
+def decide(sid, args):
+    name, data = args["tool_name"], args.get("input", {})
+    if name in store.load(sid)["session"].get("allow", []): return dict(behavior="allow", updatedInput=data)
+    s, e = store.emit(sid, "ask", "agent", f"Allow {name}?", target=None, options=OPTIONS, multi=False, ask_kind="permission", detail=preview(name, data))
+    s, answer = store.wait_for(sid, lambda s: s["asks"][e["ask"]]["answer"] or s["asks"][e["ask"]]["cancelled"], 6*3600)
+    if not answer:
+        store.emit(sid, "cancel", "orchestrate", ask=e["ask"])
+        return dict(behavior="deny", message="No answer from the user in orchestrate within 6 hours.")
+    store.emit(sid, "deliver", "orchestrate", ids=[e["ask"]])
+    choice = (answer.get("choices") or ["Deny"])[0] if isinstance(answer, dict) else "Deny"
+    if choice == "Allow always": store.emit(sid, "meta", "user", changes=dict(allow=sorted({*s["session"].get("allow", []), name})))
+    if choice.startswith("Allow"): return dict(behavior="allow", updatedInput=data)
+    return dict(behavior="deny", message=f"The user denied {name} in orchestrate." + (f" Note: {answer['text']}" if answer.get("text") else ""))
+
+def main():
+    sid = os.environ["CONVOS_ORCHESTRATE_SESSION"]
+    def reply(rid, result=None, error=None):
+        sys.stdout.write(json.dumps(dict(jsonrpc="2.0", id=rid, **(dict(error=error) if error else dict(result=result)))) + "\n")
+        sys.stdout.flush()
+    for line in sys.stdin:
+        if not line.strip(): continue
+        req = json.loads(line)
+        method, rid = req.get("method"), req.get("id")
+        if rid is None: continue
+        if method == "initialize": reply(rid, dict(protocolVersion=req["params"]["protocolVersion"], capabilities=dict(tools={}), serverInfo=dict(name="orchestrate", version="1")))
+        elif method == "tools/list": reply(rid, dict(tools=[TOOL]))
+        elif method == "tools/call":
+            try: reply(rid, dict(content=[dict(type="text", text=json.dumps(decide(sid, req["params"]["arguments"])))]))
+            except (ValueError, KeyError, OSError) as error: reply(rid, dict(content=[dict(type="text", text=json.dumps(dict(behavior="deny", message=f"orchestrate error: {error}")))]))
+        elif method == "ping": reply(rid, {})
+        else: reply(rid, error=dict(code=-32601, message=f"Unknown method {method}"))
+
+if __name__ == "__main__":
+    from ai_convos import cli
+    main()

convos_orchestrate-0.11.6b37/src/ai_convos_orchestrate/runtime.py

@@ -0,0 +1,118 @@
+"""Session runtime: start, stop, and resume headless agents, and deliver the user's words to any session.
+
+Headless sessions started from the IDE are owned here and receive messages on stdin. Joined sessions
+receive them through their provider's own channel (Claude Code messaging socket, codex queue);
+whatever cannot be delivered stays pending for the agent's `inbox`.
+"""
+import collections, json, os, signal, subprocess, sys, threading, time, uuid
+from pathlib import Path
+from . import store, channels
+
+PROVIDERS = {"claude-code": dict(label="Claude Code", models=["claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "claude-fable-5-1"], efforts=["low", "medium", "high", "xhigh", "max"], permissions=["default", "acceptEdits", "plan", "bypassPermissions"])}
+INHERITED = ("CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_MESSAGING_SOCKET", "CLAUDE_CODE_MESSAGING_TOKEN", "CLAUDE_PID", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_CHILD_SESSION", "CLAUDE_CODE_SESSION_ATTENDED", "CLAUDE_EFFORT", "CODEX_THREAD_ID", "CODEX_SESSION_ID", "CONVOS_ORCHESTRATE_SCOPE", "CONVOS_ORCHESTRATE_AS")
+SYSTEM = ("You were started from Convos Orchestrate, the user's agentic IDE (orchestrate session {sid}). The user watches and steers "
+          "you there, not in a terminal. Report your work with the orchestrate skill's tools (`convos orchestrate ...`; this session is "
+          "preselected, do not run join). Messages beginning with [orchestrate] are the user's comments and answers from the board, "
+          "addressed to the session or a named item. Before starting, load these skills with the Skill tool: {skills}.")
+PROCS, LOCK = {}, threading.RLock()
+
+def alive(sid): return (p := PROCS.get(sid)) is not None and p["proc"].poll() is None
+def busy(sid): return alive(sid) and PROCS[sid]["busy"]
+
+def set_runtime(sid, state, **extra):
+    s = store.load(sid)
+    if (s["runtime"] or {}).get("state") != state or extra: store.emit(sid, "runtime", "orchestrate", runtime=dict(state=state, **extra))
+
+def child_env(sid):
+    env = {k: v for k, v in os.environ.items() if k not in INHERITED}
+    return {**env, "CONVOS_ORCHESTRATE_SESSION": sid}
+
+def command(sid, meta, resume):
+    mcp = dict(mcpServers=dict(orchestrate=dict(command=sys.executable, args=["-m", "ai_convos_orchestrate.mcp"], env={k: v for k, v in child_env(sid).items() if k.startswith(("CONVOS_", "PATH", "HOME"))})))
+    skills = ", ".join(["orchestrate", *[k for k in meta.get("skills", []) if k != "orchestrate"]])
+    return ["claude", "-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose",
+            "--model", meta["model"], *(["--effort", meta["effort"]] if meta.get("effort") else []),
+            *(["--resume", meta["provider_session"]] if resume else ["--session-id", meta["provider_session"]]),
+            "--permission-mode", meta.get("permission") or "default", "--allowedTools", "Bash(convos orchestrate:*)",
+            "--append-system-prompt", SYSTEM.format(sid=sid, skills=skills),
+            "--mcp-config", json.dumps(mcp), "--permission-prompt-tool", "mcp__orchestrate__permission"]
+
+def start(sid, text=None):
+    """Start (or resume) a managed session's process; optionally send it a user turn."""
+    with LOCK:
+        if not alive(sid):
+            s = store.load(sid)
+            meta, resume = s["session"], s["runtime"] is not None and s["runtime"].get("started")
+            if meta["origin"] != "gui": raise ValueError("Only sessions started from orchestrate can be started here; joined sessions run in their own terminal")
+            if meta["provider"] not in PROVIDERS: raise ValueError(f"Provider {meta['provider']} cannot be started headless yet")
+            if not Path(meta["cwd"]).is_dir(): raise ValueError(f"Working directory is missing: {meta['cwd']}")
+            log = open(store.sdir(sid)/"stderr.log", "ab")
+            proc = subprocess.Popen(command(sid, meta, resume), cwd=meta["cwd"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=log, env=child_env(sid), start_new_session=True)
+            PROCS[sid] = dict(proc=proc, busy=False, log=log)
+            threading.Thread(target=read, args=(sid, proc), daemon=True, name=f"orchestrate-{sid}").start()
+            set_runtime(sid, "idle", started=True, pid=proc.pid)
+        if text: send(sid, text)
+
+def send(sid, text):
+    with LOCK:
+        proc = PROCS[sid]["proc"]
+        proc.stdin.write((json.dumps(dict(type="user", message=dict(role="user", content=[dict(type="text", text=text)]))) + "\n").encode())
+        proc.stdin.flush()
+        PROCS[sid]["busy"] = True
+    set_runtime(sid, "working", started=True, pid=proc.pid)
+
+def read(sid, proc):
+    """The board is what the agent reports; its raw output only tells us when a turn ends."""
+    for raw in proc.stdout:
+        try: event = json.loads(raw)
+        except ValueError: continue
+        if event.get("type") == "result":
+            PROCS[sid]["busy"] = False
+            set_runtime(sid, "idle", started=True, pid=proc.pid, cost=event.get("total_cost_usd"), turns=event.get("num_turns"))
+    code = proc.wait()
+    with LOCK:
+        if PROCS.get(sid, {}).get("proc") is proc: PROCS.pop(sid)["log"].close()
+    set_runtime(sid, "stopped" if code in (0, -signal.SIGTERM, -signal.SIGINT, 128+signal.SIGTERM, 128+signal.SIGINT) else "failed", started=True, code=code)
+
+def stop(sid):
+    with LOCK: proc = PROCS.get(sid, {}).get("proc")
+    if proc is None or proc.poll() is not None: return set_runtime(sid, "stopped", started=True)
+    os.killpg(proc.pid, signal.SIGTERM)
+    try: proc.wait(8)
+    except subprocess.TimeoutExpired: os.killpg(proc.pid, signal.SIGKILL)
+
+def settle():
+    """After a reboot or server restart, no managed process survives: record that truthfully."""
+    for sid in store.session_ids():
+        s = store.load(sid)
+        if s["session"]["origin"] == "gui" and (s["runtime"] or {}).get("state") in ("working", "idle", "starting") and not alive(sid):
+            store.emit(sid, "runtime", "orchestrate", runtime={**{k: v for k, v in s["runtime"].items() if k != "at"}, "state": "stopped"})
+
+def spawn(title, cwd, prompt, model, effort=None, skills=(), permission="default", parent=None, provider="claude-code"):
+    if provider not in PROVIDERS: raise ValueError(f"Unknown provider {provider}")
+    if model not in PROVIDERS[provider]["models"]: raise ValueError(f"Unknown model {model}")
+    if not Path(cwd).expanduser().is_dir(): raise ValueError(f"No such directory: {cwd}")
+    if parent:
+        psid, _, pitem = parent.partition(":")
+        if pitem and pitem not in store.load(psid)["items"]: raise ValueError(f"Parent item {parent} does not exist")
+    meta = dict(id=(sid := store.new_id()), title=title.strip() or prompt.strip().splitlines()[0][:80], provider=provider, provider_session=str(uuid.uuid4()), model=model, effort=effort or None, cwd=str(Path(cwd).expanduser().resolve()), origin="gui", parent=parent or None, skills=sorted(set(skills) | {"orchestrate"}), permission=permission)
+    store.emit(sid, "open", "user", prompt, session=meta)
+    start(sid, prompt)
+    return sid
+
+def message(s, found):
+    who = "from the user" if all(p["actor"] == "user" or p["type"] == "answer" for p in found) else "on your board"
+    return "\n".join([f"[orchestrate] {len(found)} new {who} (session {s['session']['id']}):", *[store.describe(s, p) for p in found]])
+
+DELIVERING = collections.defaultdict(threading.Lock)
+
+def deliver(sid):
+    """Route undelivered user words to the session exactly once. Returns the channel used, or 'pending' when the agent must pull."""
+    with DELIVERING[sid]:
+        s = store.load(sid)
+        if not (found := store.pending(s)): return None
+        text, meta = message(s, found), s["session"]
+        if meta["origin"] == "gui": (start(sid, text), route := "stdin")
+        elif not (route := channels.push(sid, meta, text)): return "pending"
+        store.emit(sid, "deliver", "orchestrate", ids=[p["id"] for p in found], channel=route)
+        return route