@sandagent/daemon 0.8.5

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,378 @@
+# @sandagent/daemon
+
+Unified API gateway for sandbox containers. Runs **inside** the [sandock](~/Documents/kapps/apps/sandock) Next.js app — either embedded as a Next.js route handler (local/dev mode) or as a standalone process inside a sandbox container (production).
+
+---
+
+## Where this runs
+
+```
+~/Documents/kapps/apps/buda/        ← buda.im Next.js app
+    app/api/daemon/[...path]/
+        route.ts                    ← embeds @sandagent/daemon via createNextHandler()
+                                       (local dev mode, no extra process)
+
+sandbox container                   ← production
+    sandagent-daemon :3080          ← standalone process
+    (accessed via sandock.ai proxy)
+```
+
+The same `@sandagent/daemon` package works in both modes — Next.js embed for local development, standalone HTTP server for production containers.
+
+---
+
+## Architecture
+
+### 1. Big Picture — How Buda talks to a sandbox
+
+```
+  buda.im
+     │
+     │  HTTPS
+     ▼
+  sandock.ai
+  /api/v1/sandbox/http/proxy/{sandbox-id}/3080/
+     │
+     │  HTTP (proxied)
+     ▼
+┌─────────────────────────────────────────────────────┐
+│           sandbox container                         │
+│                                                     │
+│   ┌────────────────────────────────────┐            │
+│   │       sandagent-daemon :3080       │            │
+│   │       (unified API gateway)        │            │
+│   └────────────────────────────────────┘            │
+│                                                     │
+│   chromium :9223 (internal) --remote-allow-origins=*│
+│   nginx :9222 → :9223  (rewrites Host: localhost)   │
+└─────────────────────────────────────────────────────┘
+```
+
+External callers only ever see **one port: 3080**. Everything else is internal.
+
+---
+
+### 2. Inside the daemon — request routing
+
+```
+incoming HTTP request
+        │
+        ▼
+┌───────────────────────────────────────────────────────┐
+│                  sandagent-daemon                     │
+│                                                       │
+│  POST /api/coding/run  ──────────────────────────┐ │
+│                                                     │ │
+│  GET|POST /api/fs/*   ──────────────────────────┐  │ │
+│  GET|POST /api/git/*  ──────────────────────┐   │  │ │
+│  GET|POST /api/volumes/*  ──────────────┐   │   │  │ │
+│  GET /healthz  ─────────────────────┐   │   │   │  │ │
+│                                     │   │   │   │  │ │
+│                                     ▼   ▼   ▼   │  │ │
+│                               ┌─────────────┐   │  │ │
+│                               │ DaemonRouter│   │  │ │
+│                               │ (core logic)│   │  │ │
+│                               └──────┬──────┘   │  │ │
+│                                      │          │  │ │
+│              ┌───────────────────────┤          │  │ │
+│              ▼                       ▼          ▼  │ │
+│         node:fs/promises        spawn git      SSE │ │
+│         (file ops)              (git CLI)   stream │ │
+│                                                    │ │
+│                                    @sandagent/     │ │
+│                                    runner-core ◄───┘ │
+│                                    claude/pi/        │
+│                                    gemini/codex      │
+└───────────────────────────────────────────────────────┘
+```
+
+---
+
+### 3. Package dependency graph
+
+```
+packages/
+│
+├── runner-claude   ──┐
+├── runner-codex    ──┤
+├── runner-gemini   ──┼──► runner-core ◄──┬── apps/runner-cli
+├── runner-pi       ──┤                   │
+└── runner-opencode ──┘                   └── apps/sandagent-daemon
+```
+
+`runner-core` is the shared dispatch layer — no I/O, no stdout, just `createRunner() → AsyncIterable<string>`.
+
+---
+
+### 4. Deployment modes
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Mode A: Standalone process (container / local)                  │
+│                                                                  │
+│  entrypoint.sh                                                   │
+│  ├── chromium :9223 (internal) --remote-allow-origins=* &        │
+│  ├── nginx :9222 → :9223 (rewrites Host: localhost) &            │
+│  └── sandagent-daemon          ← node process, listens :3080     │
+│                                                                  │
+│  caller: curl / Buda SDK / any HTTP client                       │
+│  → http://sandbox:3080/api/fs/read?path=file.txt                 │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│  Mode B: Embedded in Next.js (local dev / sandock-cli)           │
+│                                                                  │
+│  app/api/daemon/[...path]/route.ts                               │
+│  └── createNextHandler({ root: process.cwd() })                  │
+│                                                                  │
+│  No extra process. DaemonRouter runs inside Next.js.             │
+│  caller: browser / fetch                                         │
+│  → /api/daemon/fs/read?path=file.txt                             │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│  Mode C: runner-cli (local terminal, no daemon needed)           │
+│                                                                  │
+│  sandagent run --runner claude -- "Build a REST API"             │
+│  └── runner-core → stdout (AI SDK UI NDJSON stream)              │
+│                                                                  │
+│  Runs directly on local filesystem. No HTTP server.              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 5. Internal code structure
+
+```
+apps/sandagent-daemon/
+├── src/
+│   ├── cli.ts          entry point — reads env, starts http.Server
+│   ├── server.ts       createDaemon() — http.Server wrapping DaemonRouter
+│   ├── router.ts       DaemonRouter — framework-agnostic route table
+│   ├── nextjs.ts       createNextHandler() — Next.js adapter
+│   ├── utils.ts        path safety, ApiEnvelope helpers
+│   └── routes/
+│       ├── health.ts   GET /healthz
+│       ├── fs.ts       GET|POST /api/fs/*
+│       ├── volumes.ts  GET|POST /api/volumes/*
+│       ├── git.ts      POST /api/git/*  (spawns git CLI)
+│       └── coding.ts POST /api/coding/run  (SSE, uses runner-core)
+└── src/__tests__/
+    └── daemon.test.ts  13 integration tests (no mocks, real fs + git)
+```
+
+---
+
+## Usage
+
+### Option A: runner-cli (local terminal)
+
+```bash
+cd templates/coder
+npx sandagent run -- "Build a REST API"
+npx sandagent run --runner pi -- "Analyze this dataset"
+npx sandagent run --runner gemini --model gemini-2.0-flash -- "Review my code"
+npx sandagent run --resume <session-id> -- "Continue"
+```
+
+Output: raw AI SDK UI NDJSON stream to stdout.
+
+### Option B: daemon standalone (container)
+
+```bash
+# see docs/entrypoint.example.sh for the full script
+#
+# Chromium runs on internal port 9223 with --remote-allow-origins=* so
+# the WebSocket origin check passes. nginx proxies 0.0.0.0:9222 → 9223
+# and rewrites the Host header to "localhost" to satisfy Chromium's
+# DNS-rebinding security check. Without this rewrite, external clients
+# (Host: container-ip:9222) are rejected even when the port is open.
+chromium --headless --no-sandbox \
+  --remote-debugging-port=9223 \
+  --remote-allow-origins=* &
+nginx  # proxies :9222 → :9223 with Host rewrite
+exec sandagent-daemon
+```
+
+```bash
+# Run an agent — SSE stream
+curl -N -X POST http://localhost:3080/api/coding/run \
+  -H 'Content-Type: application/json' \
+  -d '{"runner":"claude","userInput":"List files in /workspace"}'
+
+# File ops
+curl -X POST http://localhost:3080/api/fs/write \
+  -H 'Content-Type: application/json' \
+  -d '{"path":"hello.txt","content":"hello world"}'
+
+curl "http://localhost:3080/api/fs/read?path=hello.txt"
+
+# Git
+curl -X POST http://localhost:3080/api/git/clone \
+  -H 'Content-Type: application/json' \
+  -d '{"repo_parent":".","url":"https://github.com/user/repo","depth":1}'
+```
+
+### Option C: embed in Next.js
+
+```ts
+// app/api/daemon/[...path]/route.ts
+import { createNextHandler } from "@sandagent/daemon/nextjs";
+
+const handler = createNextHandler({ root: process.cwd() });
+export const GET = handler;
+export const POST = handler;
+```
+
+Covers `/api/fs/*`, `/api/git/*`, `/api/volumes/*` at `/api/daemon/*`. No extra process.
+
+### Option D: just run an agent directly (no daemon needed)
+
+If you only need to run an agent — no file API, no HTTP server — use `runner-core` directly:
+
+```ts
+import { createRunner } from "@sandagent/runner-core";
+
+const stream = createRunner({
+  runner: "claude",           // or "pi", "gemini", "codex", "opencode"
+  model: "claude-sonnet-4-20250514",
+  userInput: "Build a REST API",
+  cwd: "/workspace",
+  env: process.env as Record<string, string>,
+});
+
+// Collect all chunks into a full response
+const chunks: string[] = [];
+for await (const chunk of stream) {
+  chunks.push(chunk);
+}
+const fullResponse = chunks.join("");
+
+// Or parse each NDJSON line as it arrives
+for await (const chunk of stream) {
+  for (const line of chunk.split("\n").filter(Boolean)) {
+    const msg = JSON.parse(line);
+    console.log(msg);
+  }
+}
+```
+
+`runner-core` is the shared core used by both `runner-cli` and `sandagent-daemon`. Use it directly when you don't need the HTTP gateway.
+
+---
+
+## API Reference
+
+All JSON responses: `{ "ok": true, "data": {}, "error": null }`
+
+### Agent `/api/coding/*`
+
+#### `POST /api/coding/run`
+
+Run an agent and stream the output as SSE (AI SDK UI NDJSON format).
+
+Request body:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `userInput` | string | required | The task / prompt |
+| `runner` | string | `"claude"` | `claude` · `codex` · `gemini` · `pi` · `opencode` |
+| `model` | string | `"claude-sonnet-4-20250514"` | Model name for the runner |
+| `cwd` | string | `SANDAGENT_ROOT` | Working directory inside the sandbox |
+| `systemPrompt` | string | — | Override system prompt |
+| `maxTurns` | number | — | Max agent turns |
+| `allowedTools` | string[] | — | Restrict which tools the agent can use |
+| `resume` | string | — | Session ID to resume |
+| `skillPaths` | string[] | — | Extra skill paths (pi runner) |
+
+Example:
+
+```bash
+# Stream with curl (-N disables buffering)
+curl -N -X POST http://localhost:3080/api/coding/run \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "runner": "claude",
+    "userInput": "List all TypeScript files and summarize what each does",
+    "cwd": "/workspace/myproject"
+  }'
+
+# Use pi runner with a different model
+curl -N -X POST http://localhost:3080/api/coding/run \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "runner": "pi",
+    "model": "gemini-2.0-flash",
+    "userInput": "Refactor this codebase to use async/await"
+  }'
+```
+
+Response: `application/x-ndjson` chunked stream — each line is an AI SDK UI message, compatible with Vercel AI SDK `useChat` / `streamText`.
+
+### Filesystem `/api/fs/*`
+
+| Method | Path | Params |
+|--------|------|--------|
+| GET | `/api/fs/list` | `?path=src&volume=vol-001` |
+| GET | `/api/fs/read` | `?path=file.txt` |
+| GET | `/api/fs/stat` | `?path=file.txt` |
+| GET | `/api/fs/exists` | `?path=file.txt` |
+| GET | `/api/fs/find` | `?pattern=todo&limit=100` |
+| POST | `/api/fs/write` | `{"path":"a.txt","content":"hello"}` |
+| POST | `/api/fs/append` | `{"path":"log.txt","content":"line\n"}` |
+| POST | `/api/fs/mkdir` | `{"path":"a/b/c"}` |
+| POST | `/api/fs/remove` | `{"path":"tmp","recursive":true}` |
+| POST | `/api/fs/move` | `{"from":"a.txt","to":"b.txt"}` |
+| POST | `/api/fs/copy` | `{"from":"a.txt","to":"b.txt"}` |
+
+All fs endpoints accept optional `volume` for multi-tenant isolation.
+
+### Git `/api/git/*`
+
+| Method | Path | Body |
+|--------|------|------|
+| POST | `/api/git/status` | `{"repo":"myrepo"}` |
+| POST | `/api/git/exec` | `{"repo":"myrepo","args":["log","--oneline"]}` |
+| POST | `/api/git/clone` | `{"repo_parent":".","url":"https://...","depth":1}` |
+| POST | `/api/git/init` | `{"repo":"myrepo","initial_branch":"main"}` |
+
+### Volumes `/api/volumes/*`
+
+| Method | Path | Body |
+|--------|------|------|
+| GET | `/api/volumes/list` | |
+| POST | `/api/volumes/ensure` | `{"volume":"vol-001"}` |
+| POST | `/api/volumes/remove` | `{"volume":"vol-001"}` |
+
+### Health
+
+```
+GET /healthz
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SANDAGENT_DAEMON_PORT` | `3080` | Listen port |
+| `SANDAGENT_ROOT` | `/workspace` | Filesystem root |
+| `ANTHROPIC_API_KEY` | — | For claude runner |
+| `GEMINI_API_KEY` | — | For gemini / pi runner |
+| `OPENAI_API_KEY` | — | For codex runner |
+
+---
+
+## Development
+
+```bash
+cd apps/sandagent-daemon
+pnpm install && pnpm build
+
+SANDAGENT_ROOT=/tmp/test sandagent-daemon
+curl http://localhost:3080/healthz
+
+pnpm test   # 13 integration tests
+```