@shardflux/cli 0.13.6 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.14.0
+
+- Parallel conversation launches preserve both sessions in local history.
+
+- Help an agent can set up cloud agents from: `shard --help` has a Cloud agents section (conversations, machine, template, agents) and says how a VM is made (the coding template, then your machine, then the project template), that machine and project templates are saved from an agent's VM, that `shard templates` is for your own app's workspaces (a repository bound to one is refused with `template_not_agent_capable`), and that Claude Code and Codex in the VM have the `shardflux-computer` tools. `shard machine`, `shard template` and `shard templates init|build|draft open` help say the same.
+- Register one desktop app connection per project, named Shardflux · <project>; preserve older SSH aliases and CLI 0.13.x target manifests.
+- Resume saved conversations in a fresh VM under the same identity; open a read-only project-space reader for final branches and transcripts.
+- Conversation follow-up: read-only reviewer joins, Try locally device requests, and project usage with workspace-scoped guest resize.
+
+- **Breaking:** `shard ./` starts a conversation in its own VM and opens Claude Code or Codex directly. `--resume` selects a saved project conversation. Two-way sync is now opened with `shard conversations try <name>` in an isolated local worktree.
+- Register one Shardflux provider in T3 Code silently, with Claude Code and Codex models. ACP sessions attach to guest supervision and replay missed updates after reconnect.
+- Run device tools through the Mac helper with local approvals and project grants; mirror transcripts into the Shardflux stash and hand ended sessions to native history after fetching their branch.
+- Volume lists and details show `kind`; project-space quota is labelled platform managed. Includes SDK 0.19.0.
+- Add project conversations with durable VM bindings, messages, moves, landing records and device requests.
+
+- Local connections to the target-update lock cannot keep its owner running after release.
+
+- `ssh-proxy` closes its guest forwarder on EOF, signals and transport failure, reuses the cached helper, and waits for target updates with automatic recovery of dead PID owners.
+- `ssh-proxy` finishes when the guest closes its output, including sshd's pre-authentication admission refusals, so OpenSSH receives EOF and reconnects without hanging.
+
+- Fork externally started desktop/SDK agent workspaces as full-state copies without a managed PTY receipt; give copied T3 workspaces their own identity even when an older platform's PTY repair fails.
+- The managed `~/.ssh/config` Include line is written unquoted when the path needs no quotes, so tools that list SSH hosts from it (T3 Code) find Shardflux hosts.
+- Open cloud projects in T3 Code with `shard agents open t3 <key>`, prewarm its matching server in the background, name environments `Shardflux · <project>`, and give forked agents a separate T3 identity.
+- `shard ssh-proxy` sends a prewake hint and uses a passive tunnel so open desktop SSH connections join the existing parking lifecycle.
+- `shard ssh-proxy` connects to a workspace whose host has no passive attach as an ordinary SSH connection.
+- `shard` exits quietly when the reader has closed its output (OpenSSH after a `ssh-proxy` session, `| head`), instead of printing a write error.
+- An error with several causes (tunnel teardown, cleanup) names each cause, and its first cause decides the error code.
+
 ## 0.13.6
 
 - `shard` makes the macOS menu bar app's executable runnable when it installs or starts the app, so a menu bar copied

package/README.md

@@ -52,7 +52,7 @@ Use `shard` for your projects, machine, templates and account.
 
 ## Quick start
 
-Start your coding agent on a local project (0.13.2+):
+Start a conversation on a local project (0.14.0+):
 
 ```sh
 shard setup
@@ -61,10 +61,24 @@ shard ./
 ```
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
-The agent is usable immediately while setup prepares the project in the background. `shard` opens the command
-center for every project; `shard ./` returns to this project. On macOS the menu bar starts automatically the first
+Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
+VM; `shard ./ --resume` selects a saved project conversation. You can open conversations in separate terminals at the same time; each stays in the project's local history. `shard` opens the optional command center. On macOS the menu bar starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
+T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
+The provider is registered automatically when T3 Code is installed. Use a T3 build that supports ACP providers.
+
+To try a conversation on your Mac:
+
+```sh
+shard conversations try <conversation>
+```
+
+Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev servers appear at localhost.
+Ctrl-C stops local sync. Your main checkout stays available for your own work.
+Device tools ask Allow once or Always for this project on your Mac. Live transcripts stay in
+`~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history.
+
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
 
@@ -1163,4 +1177,26 @@ Remembered credentials: stored encrypted with AWS KMS and filled straight into t
 [Machine and template](https://docs.shardflux.dev/guides/machine-and-template) ·
 [Credentials](https://docs.shardflux.dev/guides/credentials)
 
-`shard templates` remains the platform template build and management group.
+A VM is the `coding` template, then your machine, then the project template. Machine and project templates are
+always saved from an agent's VM, so they keep Claude Code, Codex and the agent runtime. `shard templates` builds
+templates for your own app's workspaces (SDK/API), not for cloud agents: a repository bound to one of those is
+refused with `template_not_agent_capable` (0.14.0+).
+
+Inside the VM, Claude Code and Codex have Shardflux computer use next to their own tools (0.14.0+, `coding` 13+): the
+`shardflux-computer` MCP server's `computer` and `computer_batch` drive the VM's desktop. The agent starts a program
+on it with `DISPLAY=:1`, for example `DISPLAY=:1 chromium http://localhost:3000 &`, then takes a screenshot.
+
+Volume lists and details (0.14.0+) show `kind`. Project spaces show their measured storage and a platform-managed quota.
+
+## Conversations
+
+From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.
+
+
+Desktop project connections (0.14.0+): `shard agents open codex-app <project>/<workspace>` and
+`shard agents open claude-desktop <project>/<workspace>` register **Shardflux · <project>** in the app.
+Open that project connection to start conversations and return to their saved threads.
+
+Conversation JSON includes `join_mode` and the worktree used by reviewers and workers.
+
+`shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.

package/dist/acp-catalog.d.ts

@@ -0,0 +1,152 @@
+export declare const ACP_CATALOG: {
+    claude: {
+        initialize: {
+            protocolVersion: number;
+            agentCapabilities: {
+                _meta: {
+                    claudeCode: {
+                        promptQueueing: boolean;
+                    };
+                    authStatus: {};
+                };
+                promptCapabilities: {
+                    image: boolean;
+                    embeddedContext: boolean;
+                };
+                mcpCapabilities: {
+                    http: boolean;
+                    sse: boolean;
+                };
+                auth: {
+                    logout: {};
+                };
+                providers: {};
+                loadSession: boolean;
+                sessionCapabilities: {
+                    additionalDirectories: {};
+                    close: {};
+                    delete: {};
+                    fork: {};
+                    list: {};
+                    resume: {};
+                    subagents: {};
+                };
+            };
+            agentInfo: {
+                name: string;
+                title: string;
+                version: string;
+            };
+            authMethods: never[];
+            _meta: {
+                steering: {
+                    supported: boolean;
+                };
+            };
+        };
+        session: {
+            modes: {
+                currentModeId: string;
+                availableModes: {
+                    id: string;
+                    name: string;
+                    description: string;
+                }[];
+            };
+            configOptions: {
+                id: string;
+                name: string;
+                description: string;
+                category: string;
+                type: string;
+                currentValue: string;
+                options: {
+                    value: string;
+                    name: string;
+                    description: string;
+                }[];
+            }[];
+        };
+    };
+    codex: {
+        initialize: {
+            protocolVersion: number;
+            agentInfo: {
+                name: string;
+                title: string;
+                version: string;
+            };
+            agentCapabilities: {
+                auth: {
+                    logout: {};
+                };
+                providers: {};
+                loadSession: boolean;
+                promptCapabilities: {
+                    embeddedContext: boolean;
+                    image: boolean;
+                };
+                sessionCapabilities: {
+                    resume: {};
+                    list: {};
+                    close: {};
+                    delete: {};
+                    fork: {};
+                    additionalDirectories: {};
+                    subagents: {};
+                };
+                mcpCapabilities: {
+                    acp: boolean;
+                    http: boolean;
+                    sse: boolean;
+                };
+                _meta: {
+                    authStatus: {};
+                };
+            };
+            authMethods: ({
+                id: string;
+                name: string;
+                description: string;
+                _meta: {
+                    "api-key": {
+                        provider: string;
+                    };
+                };
+            } | {
+                id: string;
+                name: string;
+                description: string;
+                _meta?: undefined;
+            })[];
+            _meta: {
+                steering: {
+                    supported: boolean;
+                };
+            };
+        };
+        session: {
+            modes: {
+                availableModes: {
+                    id: string;
+                    name: string;
+                    description: string;
+                }[];
+                currentModeId: string;
+            };
+            configOptions: {
+                id: string;
+                name: string;
+                description: string;
+                category: string;
+                type: string;
+                currentValue: string;
+                options: {
+                    value: string;
+                    name: string;
+                    description: string;
+                }[];
+            }[];
+        };
+    };
+};

package/dist/acp-catalog.js

@@ -0,0 +1,287 @@
+// Captured from the pinned adapters; refreshed when their versions change.
+export const ACP_CATALOG = {
+    "claude": {
+        "initialize": {
+            "protocolVersion": 1,
+            "agentCapabilities": {
+                "_meta": {
+                    "claudeCode": {
+                        "promptQueueing": true
+                    },
+                    "authStatus": {}
+                },
+                "promptCapabilities": {
+                    "image": true,
+                    "embeddedContext": true
+                },
+                "mcpCapabilities": {
+                    "http": true,
+                    "sse": true
+                },
+                "auth": {
+                    "logout": {}
+                },
+                "providers": {},
+                "loadSession": true,
+                "sessionCapabilities": {
+                    "additionalDirectories": {},
+                    "close": {},
+                    "delete": {},
+                    "fork": {},
+                    "list": {},
+                    "resume": {},
+                    "subagents": {}
+                }
+            },
+            "agentInfo": {
+                "name": "@agentclientprotocol/claude-agent-acp",
+                "title": "Claude Agent",
+                "version": "0.87.0"
+            },
+            "authMethods": [],
+            "_meta": {
+                "steering": {
+                    "supported": true
+                }
+            }
+        },
+        "session": {
+            "modes": {
+                "currentModeId": "auto",
+                "availableModes": [
+                    {
+                        "id": "default",
+                        "name": "Manual",
+                        "description": "Always ask before making changes"
+                    },
+                    {
+                        "id": "acceptEdits",
+                        "name": "Accept edits",
+                        "description": "Automatically accept all file edits"
+                    },
+                    {
+                        "id": "plan",
+                        "name": "Plan",
+                        "description": "Create a plan before making changes"
+                    },
+                    {
+                        "id": "auto",
+                        "name": "Auto",
+                        "description": "Claude handles permission decisions"
+                    },
+                    {
+                        "id": "bypassPermissions",
+                        "name": "Bypass permissions",
+                        "description": "Accepts all permissions"
+                    }
+                ]
+            },
+            "configOptions": [
+                {
+                    "id": "model",
+                    "name": "Model",
+                    "description": "AI model to use",
+                    "category": "model",
+                    "type": "select",
+                    "currentValue": "opus",
+                    "options": [
+                        {
+                            "value": "default",
+                            "name": "Default (recommended)",
+                            "description": "Opus 5.5"
+                        },
+                        {
+                            "value": "opus",
+                            "name": "Opus 5.5",
+                            "description": "Best for everyday, complex tasks"
+                        },
+                        {
+                            "value": "fable",
+                            "name": "Fable 5.1",
+                            "description": "Most capable for your hardest and longest-running tasks"
+                        },
+                        {
+                            "value": "sonnet",
+                            "name": "Sonnet 5.5",
+                            "description": "Efficient for routine tasks"
+                        },
+                        {
+                            "value": "haiku",
+                            "name": "Haiku 4.5",
+                            "description": "Fastest for quick answers"
+                        },
+                        {
+                            "value": "claude-sonnet-5",
+                            "name": "Sonnet 5",
+                            "description": "Efficient for routine tasks"
+                        },
+                        {
+                            "value": "claude-opus-5",
+                            "name": "Opus 5",
+                            "description": "Best for everyday, complex tasks"
+                        },
+                        {
+                            "value": "claude-fable-5",
+                            "name": "Fable 5",
+                            "description": "Most capable for your hardest and longest-running tasks"
+                        },
+                        {
+                            "value": "claude-opus-4-8",
+                            "name": "Opus 4.8",
+                            "description": "Best for everyday, complex tasks"
+                        },
+                        {
+                            "value": "claude-opus-4-7",
+                            "name": "Opus 4.7",
+                            "description": "Best for everyday, complex tasks"
+                        },
+                        {
+                            "value": "claude-opus-4-6",
+                            "name": "Opus 4.6",
+                            "description": "Best for everyday, complex tasks"
+                        },
+                        {
+                            "value": "claude-sonnet-4-6",
+                            "name": "Sonnet 4.6",
+                            "description": "Efficient for routine tasks"
+                        }
+                    ]
+                }
+            ]
+        }
+    },
+    "codex": {
+        "initialize": {
+            "protocolVersion": 1,
+            "agentInfo": {
+                "name": "@agentclientprotocol/codex-acp",
+                "title": "Codex",
+                "version": "2.1.1"
+            },
+            "agentCapabilities": {
+                "auth": {
+                    "logout": {}
+                },
+                "providers": {},
+                "loadSession": true,
+                "promptCapabilities": {
+                    "embeddedContext": true,
+                    "image": true
+                },
+                "sessionCapabilities": {
+                    "resume": {},
+                    "list": {},
+                    "close": {},
+                    "delete": {},
+                    "fork": {},
+                    "additionalDirectories": {},
+                    "subagents": {}
+                },
+                "mcpCapabilities": {
+                    "acp": false,
+                    "http": true,
+                    "sse": false
+                },
+                "_meta": {
+                    "authStatus": {}
+                }
+            },
+            "authMethods": [
+                {
+                    "id": "api-key",
+                    "name": "API Key",
+                    "description": "Use an API key to authenticate",
+                    "_meta": {
+                        "api-key": {
+                            "provider": "openai"
+                        }
+                    }
+                },
+                {
+                    "id": "chat-gpt",
+                    "name": "ChatGPT",
+                    "description": "Use ChatGPT to authenticate"
+                }
+            ],
+            "_meta": {
+                "steering": {
+                    "supported": true
+                }
+            }
+        },
+        "session": {
+            "modes": {
+                "availableModes": [
+                    {
+                        "id": "read-only",
+                        "name": "Read-only",
+                        "description": "Requires approval to edit files and access the internet."
+                    },
+                    {
+                        "id": "workspace-write",
+                        "name": "Workspace access",
+                        "description": "Edit workspace files; ask before writing outside the workspace or accessing the network."
+                    },
+                    {
+                        "id": "agent",
+                        "name": "Auto review",
+                        "description": "Only ask for actions detected as potentially unsafe"
+                    },
+                    {
+                        "id": "agent-full-access",
+                        "name": "Full access",
+                        "description": "Unrestricted access to the internet and any file on your computer"
+                    }
+                ],
+                "currentModeId": "agent"
+            },
+            "configOptions": [
+                {
+                    "id": "model",
+                    "name": "Model",
+                    "description": "Model Codex uses for the session",
+                    "category": "model",
+                    "type": "select",
+                    "currentValue": "gpt-6-astra",
+                    "options": [
+                        {
+                            "value": "gpt-6.1-sol",
+                            "name": "6.1 Sol",
+                            "description": "Latest workhorse model for coding and everyday work."
+                        },
+                        {
+                            "value": "gpt-6-astra",
+                            "name": "6 Astra",
+                            "description": "Frontier intelligence for the most demanding work."
+                        },
+                        {
+                            "value": "gpt-6-sol",
+                            "name": "6 Sol",
+                            "description": "Previous generation workhorse model."
+                        },
+                        {
+                            "value": "gpt-6-luna",
+                            "name": "6 Luna",
+                            "description": "Fast and affordable model for easier tasks."
+                        },
+                        {
+                            "value": "gpt-5.6-sol",
+                            "name": "5.6 Sol",
+                            "description": "Older generation workhorse model."
+                        },
+                        {
+                            "value": "gpt-5.6-terra",
+                            "name": "5.6 Terra",
+                            "description": "Older balanced model for straightforward work."
+                        },
+                        {
+                            "value": "gpt-5.6-luna",
+                            "name": "5.6 Luna",
+                            "description": "Older fast and efficient model."
+                        }
+                    ]
+                }
+            ]
+        }
+    }
+};

package/dist/acp-journal.d.ts

@@ -0,0 +1,18 @@
+import type { CellClient } from '@shardflux/sdk';
+import { AcpRpc } from './acp-rpc.js';
+import type { RpcId } from './acp-rpc.js';
+export interface AcpCursor {
+    from_seq: number;
+    prompt_id?: RpcId;
+}
+export declare const ACP_INPUT_SCRIPT = "import json, os, socket, sys\npayload = sys.stdin.buffer.readline((2 << 20) + 1024)\nif not payload.endswith(b'\\n') or len(json.dumps(json.loads(payload)['message'], separators=(',', ':'), ensure_ascii=False).encode()) > 2 << 20:\n    raise ValueError('ACP input exceeds 2 MiB')\nfolder = os.open(sys.argv[1], os.O_RDONLY)\ntry:\n    with socket.socket(socket.AF_UNIX) as peer:\n        peer.settimeout(10)\n        address = os.path.join(sys.argv[1], 'control.sock')\n        if len(address.encode()) >= 108: address = '/proc/self/fd/%d/control.sock' % folder\n        peer.connect(address)\n        peer.sendall(payload)\n        response = peer.makefile('rb').readline(65536)\n        result = json.loads(response)\n        if result.get('accepted') is not True: raise ValueError(result.get('error', 'ACP input was not acknowledged'))\n        sys.stdout.buffer.write(response)\nfinally:\n    os.close(folder)\n";
+/** Replay is finite; a live follower exists only while a turn/RPC needs output. Native supervision is CVB's. */
+export declare class AcpJournal {
+    #private;
+    readonly rpc: AcpRpc;
+    constructor(cell: CellClient, conversation: string, _harness: 'claude' | 'codex', cwd: string, cursor: AcpCursor, save: () => void, signal: AbortSignal);
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    close(): Promise<void>;
+}