@tangle-network/starter-foundry 0.7.2 → 0.13.0

package/registry/_schemas/agent.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent.schema.json",
+  "title": "AgentBundleProfile",
+  "description": "Bundle-side spec; deploy script translates into a Tangle Sandbox AgentProfile and emits harness-native files (AGENTS.md, agents.json) at the workspace root.",
+  "type": "object",
+  "required": ["name", "version", "prompt"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "version": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "harness": {
+      "type": "string",
+      "enum": ["opencode", "claude-code", "hermes"],
+      "description": "Default harness for this bundle. CLI --harness flag overrides at deploy time."
+    },
+    "hooks": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional pre/post deploy hooks. Pre runs locally before sandbox.create. Post runs inside the sandbox after files.write, before any task().",
+      "properties": {
+        "pre": { "type": "string", "description": "Path (relative to bundle root) of a script to run on the deploying machine before sandbox.create." },
+        "post": { "type": "string", "description": "Path (relative to bundle root) of a script to push into the sandbox and execute after files.write." }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Sandbox workspace layout. Defaults to OpenCode/Claude/Hermes harness convention at /home/agent.",
+      "properties": {
+        "root": {
+          "type": "string",
+          "description": "Absolute path inside the sandbox where AGENTS.md, agents.json, and resource files are emitted. Defaults to /home/agent."
+        }
+      }
+    },
+    "prompt": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "systemPromptFile": {
+          "type": "string",
+          "description": "Relative path to the orchestrator's system prompt. Conventionally AGENTS.md (auto-loaded by the harness); content is also pushed via AgentProfile.prompt.systemPrompt."
+        },
+        "instructions": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "preferred": { "type": "string" },
+        "fallback": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "tools": { "type": "object", "additionalProperties": { "type": "boolean" } },
+    "permissions": { "type": "object", "additionalProperties": { "enum": ["allow", "ask", "deny"] } },
+    "mcp": { "type": "object" },
+    "subagents": {
+      "type": "object",
+      "description": "For multi-agent bundles only. Each entry is emitted into <workspace.root>/agents.json under the OpenCode subagent shape: { mode: 'subagent', description, prompt, tools, permission, temperature }.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["systemPromptFile"],
+        "additionalProperties": false,
+        "properties": {
+          "description": { "type": "string" },
+          "systemPromptFile": { "type": "string" },
+          "model": { "type": "string" },
+          "tools": { "type": "object", "additionalProperties": { "type": "boolean" } },
+          "permissions": { "type": "object", "additionalProperties": { "enum": ["allow", "ask", "deny"] } },
+          "temperature": { "type": "number", "minimum": 0 },
+          "maxSteps": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "resources": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["source"],
+            "additionalProperties": false,
+            "properties": {
+              "source": { "type": "string", "description": "Relative to bundle root; file or directory." },
+              "target": {
+                "type": "string",
+                "description": "Path inside the sandbox. If relative, treated as relative to <workspace.root>. Defaults to <workspace.root>/<source>."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/registry/_schemas/family.schema.json

@@ -28,6 +28,11 @@
       }
     },
     "requires": { "type": "array", "items": { "type": "string" } },
+    "includes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Layer IDs to additively stack on every compose of this family — bypasses the slot mechanism. Use for multi-pick stacks like agent-runtime tool kits where every bundle gets a known set without needing N single-option slots."
+    },
     "defaults": { "type": "object" },
     "files": {
       "type": "array",
@@ -46,7 +51,7 @@
         "type": "object",
         "required": ["type"],
         "properties": {
-          "type": { "enum": ["file-exists", "node-syntax", "http-start", "command-success", "python-compile"] },
+          "type": { "enum": ["file-exists", "node-syntax", "http-start", "command-success", "python-compile", "prompt-frontmatter-valid", "cron-syntax-valid", "template-index-valid", "agents-md-valid", "methodology-index-valid", "schedule-valid"] },
           "path": { "type": "string" },
           "command": { "type": "array", "items": { "type": "string" } },
           "expect": { "type": "string" },
@@ -87,6 +92,61 @@
         "boost": { "type": "object", "additionalProperties": { "type": "number" } }
       }
     },
-    "buildHints": { "$ref": "buildhints.schema.json" }
+    "buildHints": { "$ref": "buildhints.schema.json" },
+    "domainPack": {
+      "type": "object",
+      "required": ["domain", "provides"],
+      "additionalProperties": false,
+      "properties": {
+        "domain": {
+          "type": "object",
+          "required": ["family"],
+          "additionalProperties": false,
+          "properties": {
+            "family": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "provider": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "protocol": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "runtime": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "surface": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+          }
+        },
+        "provides": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "requires": { "type": "array", "items": { "type": "string" } },
+        "ambiguityGroup": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "validationCommands": { "type": "array", "items": { "type": "string" } },
+        "authenticitySignals": { "type": "array", "items": { "type": "string" } },
+        "authenticityGroups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "signals"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "description": { "type": "string", "minLength": 1 },
+              "minRequired": { "type": "number", "minimum": 1 },
+              "signals": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 },
+                "minItems": 1
+              }
+            }
+          }
+        },
+        "routingPrompts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["prompt"],
+            "additionalProperties": false,
+            "properties": {
+              "prompt": { "type": "string", "minLength": 8 },
+              "expectedFamily": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "expectedLayers": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
   }
 }

package/registry/_schemas/layer.schema.json

@@ -54,6 +54,76 @@
         "dependencies": { "type": "object", "additionalProperties": { "type": "string" } },
         "devDependencies": { "type": "object", "additionalProperties": { "type": "string" } }
       }
+    },
+    "provides": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$" },
+      "description": "Capabilities this layer provides. Conflicts when two stacked layers provide the same capability — composer rejects unless one is explicitly preferred via spec."
+    },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$" },
+      "description": "Capabilities this layer needs from the stack. Composer topo-sorts so providers run before requirers; missing capabilities fail loud at compose time."
+    },
+    "conflictsWith": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$" },
+      "description": "Capabilities or layer ids this layer is incompatible with. Composer rejects spec if a conflicting layer is stacked alongside."
+    },
+    "domainPack": {
+      "type": "object",
+      "required": ["domain", "provides"],
+      "additionalProperties": false,
+      "properties": {
+        "domain": {
+          "type": "object",
+          "required": ["family"],
+          "additionalProperties": false,
+          "properties": {
+            "family": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "provider": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "protocol": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "runtime": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "surface": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+          }
+        },
+        "provides": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "requires": { "type": "array", "items": { "type": "string" } },
+        "ambiguityGroup": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "validationCommands": { "type": "array", "items": { "type": "string" } },
+        "authenticitySignals": { "type": "array", "items": { "type": "string" } },
+        "authenticityGroups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "signals"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "description": { "type": "string", "minLength": 1 },
+              "minRequired": { "type": "number", "minimum": 1 },
+              "signals": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 },
+                "minItems": 1
+              }
+            }
+          }
+        },
+        "routingPrompts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["prompt"],
+            "additionalProperties": false,
+            "properties": {
+              "prompt": { "type": "string", "minLength": 8 },
+              "expectedFamily": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "expectedLayers": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
     }
   }
 }

package/registry/families/agent-debug-ui-ts/files/.env.example

@@ -0,0 +1,13 @@
+# Required — Tangle sandbox API key (operator-scoped)
+VITE_TANGLE_SANDBOX_API_KEY=sk-tan-...
+
+# Required — Tangle sandbox API base URL
+VITE_TANGLE_SANDBOX_BASE_URL=https://api.tangle.tools
+
+# Required — the sandbox ID to attach to (must already exist).
+# Create one with: pnpm dlx @tangle-network/sandbox create
+VITE_SANDBOX_ID=sbx_...
+
+# Optional — override the default backend profile sent to streamPrompt().
+# Leave unset to use the sandbox's resident default.
+# VITE_BACKEND_PROFILE=named-profile

package/registry/families/agent-debug-ui-ts/files/README.md

@@ -0,0 +1,78 @@
+# {{projectName}} — agent-debug-ui-ts
+
+A Vite + React + TypeScript scaffold for **live debugging of agent runs** in
+a Tangle sandbox. Connects to a running sandbox via
+[`@tangle-network/sandbox`](https://www.npmjs.com/package/@tangle-network/sandbox),
+streams every SSE event from `streamPrompt()`, and renders four
+synchronized views over the event log.
+
+This is a **debugger**, not an agent. The agent runs inside the sandbox; this
+UI watches it work.
+
+## Views
+
+| Pane | Shows |
+| --- | --- |
+| **Chat pair** | Your prompt + the streamed assistant response. Reasoning is collapsed by default. Locks when the `result` event fires. |
+| **Event stream** | Tail of the last 50 raw SSE events — `message.part.updated`, `status`, `model-processing`, `result`, `trace.id`, `error`. Color-coded by type. Click a row to inspect. |
+| **Tool-call timeline** | Every tool part folded into a horizontal duration bar. Click a tool to jump to its first event in the inspector. |
+| **Event inspector** | Full JSON payload of any selected event or tool call. Long strings are truncated at 4 KB. |
+
+A **replay scrubber** at the bottom lets you pause the live stream and drag
+through the event log frame-by-frame for forensic review.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Fill in:
+#   VITE_TANGLE_SANDBOX_API_KEY   sk-tan-... operator-scoped
+#   VITE_TANGLE_SANDBOX_BASE_URL  https://api.tangle.tools
+#   VITE_SANDBOX_ID               sbx_... (must already exist)
+pnpm install
+pnpm dev   # http://localhost:4180
+```
+
+You need an existing sandbox with an agent runtime resident. To spin one up:
+
+```bash
+pnpm dlx @tangle-network/sandbox create --product <product-id>
+```
+
+Once the sandbox is running, open the debugger, type a prompt, hit **Run**.
+SSE events stream in real time.
+
+## SSE event contract
+
+The debugger consumes the documented sandbox SSE event types:
+
+- `message.part.updated` — streaming chunks (text / reasoning / tool parts)
+- `status` — lifecycle (`generating_response`, `processing`, `completed`, `failed`)
+- `model-processing` — phase + elapsed (`thinking`, `generating`, `tool-result`)
+- `result` — final text + token usage
+- `trace.id` — debug trace identifier
+- `error` — execution failure
+
+Streaming `delta` chunks are accumulated into part text by
+`src/lib/sandbox-stream.ts` before reaching components — the rest of the app
+only ever sees cumulative snapshots.
+
+Source contract: see the
+[Sandbox SDK INTEGRATION notes](https://github.com/tangle-network/agent-dev-container/blob/main/products/sandbox/sdk/INTEGRATION.md#sse-event-contract).
+
+## Extending
+
+- `src/lib/sandbox-stream.ts` — add transports beyond `streamPrompt()`
+  (e.g. websocket bridges, replay-from-disk for postmortems).
+- `src/components/ToolCallTimeline.tsx` — already aggregates by
+  `toolCallId`; replace `aggregateToolCalls` to add cost/latency overlays.
+- `src/lib/event-types.ts` — extend `SandboxEvent` if your runtime emits
+  custom event types (the inspector already falls through to raw JSON).
+
+## What this is NOT
+
+- **Forensic replay UI** — see the sister `agent-eval-ui-ts` family for
+  scoring + judge integration over completed runs.
+- **A marketplace / discovery surface** — see `agent-marketplace-ui-ts`.
+- **An agent runtime** — this only debugs agents that already run in a
+  sandbox. Pair with any `agent-runtime-*-ts` family.

package/registry/families/agent-debug-ui-ts/files/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang='en'>
+  <head>
+    <meta charset='UTF-8' />
+    <meta name='viewport' content='width=device-width, initial-scale=1.0' />
+    <title>{{projectName}} — Agent Debugger</title>
+  </head>
+  <body>
+    <div id='root'></div>
+    <script type='module' src='/src/main.tsx'></script>
+  </body>
+</html>

package/registry/families/agent-debug-ui-ts/files/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tangle-network/sandbox": "^0.2.1",
+    "@tangle-network/sandbox-ui": "^0.10.3",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "typescript": "^5.9.0",
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "minimumReleaseAge": 4320,
+    "minimumReleaseAgeExclude": []
+  }
+}

package/registry/families/agent-debug-ui-ts/files/src/App.tsx

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { ChatPair } from './components/ChatPair'
+import { EventInspector } from './components/EventInspector'
+import { EventStream } from './components/EventStream'
+import { ReplayScrubber } from './components/ReplayScrubber'
+import { ToolCallTimeline } from './components/ToolCallTimeline'
+import type { NormalizedEvent } from './lib/event-types'
+import { streamRun } from './lib/sandbox-stream'
+
+interface SandboxConfig {
+  baseUrl: string
+  apiKey: string
+  sandboxId: string
+}
+
+function readConfig(): { config?: SandboxConfig; missing: string[] } {
+  const env = import.meta.env
+  const baseUrl = env.VITE_TANGLE_SANDBOX_BASE_URL as string | undefined
+  const apiKey = env.VITE_TANGLE_SANDBOX_API_KEY as string | undefined
+  const sandboxId = env.VITE_SANDBOX_ID as string | undefined
+  const missing: string[] = []
+  if (!baseUrl) missing.push('VITE_TANGLE_SANDBOX_BASE_URL')
+  if (!apiKey) missing.push('VITE_TANGLE_SANDBOX_API_KEY')
+  if (!sandboxId) missing.push('VITE_SANDBOX_ID')
+  if (missing.length > 0) return { missing }
+  return {
+    config: { baseUrl: baseUrl!, apiKey: apiKey!, sandboxId: sandboxId! },
+    missing: [],
+  }
+}
+
+export function App() {
+  const { config, missing } = useMemo(() => readConfig(), [])
+
+  const [prompt, setPrompt] = useState('')
+  const [activePrompt, setActivePrompt] = useState('')
+  const [events, setEvents] = useState<NormalizedEvent[]>([])
+  const [isStreaming, setIsStreaming] = useState(false)
+  const [error, setError] = useState<string | undefined>()
+  const [selectedEventIdx, setSelectedEventIdx] = useState<number | undefined>()
+  const [selectedToolCallId, setSelectedToolCallId] = useState<string | undefined>()
+  const [isLive, setIsLive] = useState(true)
+  // Cursor for replay scrubbing — number of events to render.
+  // When live, mirrors events.length so new events stay visible.
+  const [cursor, setCursor] = useState(0)
+  const abortRef = useRef<AbortController | null>(null)
+
+  // Keep cursor pinned to the tail when in live mode.
+  useEffect(() => {
+    if (isLive) setCursor(events.length)
+  }, [events.length, isLive])
+
+  const visibleEvents = useMemo(
+    () => events.slice(0, Math.min(cursor, events.length)),
+    [events, cursor],
+  )
+
+  const selectedEvent = useMemo(
+    () =>
+      selectedEventIdx === undefined
+        ? undefined
+        : visibleEvents.find((e) => e.eventIdx === selectedEventIdx),
+    [visibleEvents, selectedEventIdx],
+  )
+
+  const handleRun = useCallback(async () => {
+    if (!config) return
+    const trimmed = prompt.trim()
+    if (!trimmed) return
+
+    abortRef.current?.abort()
+    const ac = new AbortController()
+    abortRef.current = ac
+
+    setActivePrompt(trimmed)
+    setEvents([])
+    setError(undefined)
+    setSelectedEventIdx(undefined)
+    setSelectedToolCallId(undefined)
+    setIsLive(true)
+    setCursor(0)
+    setIsStreaming(true)
+
+    try {
+      for await (const evt of streamRun({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        sandboxId: config.sandboxId,
+        prompt: trimmed,
+        signal: ac.signal,
+      })) {
+        if (ac.signal.aborted) break
+        // Functional setState so concurrent yields don't drop frames.
+        setEvents((prev) => [...prev, evt])
+      }
+    } catch (err) {
+      if (!ac.signal.aborted) {
+        setError(err instanceof Error ? err.message : String(err))
+      }
+    } finally {
+      setIsStreaming(false)
+    }
+  }, [config, prompt])
+
+  const handleStop = useCallback(() => {
+    abortRef.current?.abort()
+  }, [])
+
+  // Cancel the in-flight stream if the component unmounts.
+  useEffect(() => () => abortRef.current?.abort(), [])
+
+  if (!config) {
+    return (
+      <div className='app app--config-error'>
+        <h1>agent-debug-ui — configuration missing</h1>
+        <p>
+          Copy <code>.env.example</code> to <code>.env</code> and set the
+          following variables before starting:
+        </p>
+        <ul>
+          {missing.map((k) => (
+            <li key={k}>
+              <code>{k}</code>
+            </li>
+          ))}
+        </ul>
+        <p>
+          See <code>README.md</code> for how to point this debugger at a Tangle
+          sandbox.
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className='app'>
+      <header className='app__header'>
+        <div>
+          <h1>agent-debug-ui</h1>
+          <p className='app__subtitle'>
+            Live debugger for {config.sandboxId} via {config.baseUrl}
+          </p>
+        </div>
+        <div className='app__prompt-bar'>
+          <input
+            type='text'
+            value={prompt}
+            placeholder='Send a prompt to the sandbox agent…'
+            onChange={(e) => setPrompt(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' && !isStreaming) handleRun()
+            }}
+            disabled={isStreaming}
+          />
+          {isStreaming ? (
+            <button type='button' onClick={handleStop}>
+              Stop
+            </button>
+          ) : (
+            <button type='button' onClick={handleRun} disabled={!prompt.trim()}>
+              Run
+            </button>
+          )}
+        </div>
+      </header>
+
+      {error ? (
+        <div className='app__error'>
+          <strong>Stream error:</strong> {error}
+        </div>
+      ) : null}
+
+      <main className='app__grid'>
+        <section className='app__pane app__pane--chat'>
+          <ChatPair
+            userPrompt={activePrompt}
+            events={visibleEvents}
+            isStreaming={isStreaming && isLive}
+          />
+        </section>
+
+        <section className='app__pane app__pane--stream'>
+          <EventStream
+            events={visibleEvents}
+            selectedIdx={selectedEventIdx}
+            onSelect={(idx) => setSelectedEventIdx(idx)}
+            autoScroll={isLive}
+          />
+        </section>
+
+        <section className='app__pane app__pane--tools'>
+          <ToolCallTimeline
+            events={visibleEvents}
+            selectedToolCallId={selectedToolCallId}
+            onSelect={(toolCallId, eventIdx) => {
+              setSelectedToolCallId(toolCallId)
+              setSelectedEventIdx(eventIdx)
+            }}
+          />
+        </section>
+
+        <section className='app__pane app__pane--inspector'>
+          <EventInspector event={selectedEvent} />
+        </section>
+      </main>
+
+      <footer className='app__footer'>
+        <ReplayScrubber
+          events={events}
+          cursor={cursor}
+          onCursorChange={setCursor}
+          isLive={isLive}
+          onToggleLive={() => {
+            setIsLive((prev) => {
+              const next = !prev
+              if (next) setCursor(events.length)
+              return next
+            })
+          }}
+        />
+      </footer>
+    </div>
+  )
+}