Merge pull request #67 from fastclaw-ai/feat/runtime-backends-and-preview-ux

feat: backend-agnostic project runtime + multi-template + preview UX

Author: idoubi

cmd/fastclaw/main.go

@@ -194,9 +194,14 @@ func runGateway(port int) error {
 	// env-overridable so fastclaw stays template-agnostic — the default
 	// targets a ShipAny image with the template baked at /template.
 	if home, herr := config.HomeDir(); herr == nil {
+		// backend + shared pool let the runtime host previews through the
+		// agent's pooled executor on non-docker backends (e2b/boxlite);
+		// docker keeps its dedicated-container path. Pool is nil when
+		// sandboxing is disabled, which keeps the docker path.
 		rtMgr := coderuntime.NewManager(
 			gw.Store(), home, env.Sandbox.Image,
-			&sandbox.Policy{}, os.Getenv("FASTCLAW_PREVIEW_BASE"))
+			&sandbox.Policy{}, os.Getenv("FASTCLAW_PREVIEW_BASE"),
+			env.Sandbox.Backend, gw.SandboxPool())
 		rtMgr.RegisterTemplate("shipany-tanstack", coderuntime.TemplateSpec{
 			DevPort: 3000,
 			// Default scaffold, validated end-to-end against
@@ -217,14 +222,76 @@ func runGateway(port int) error {
 					"--exclude=node_modules --exclude=.git --exclude=.output --exclude=dist "+
 					"-cf - . | tar -C /workspace -xf -; fi; cd /workspace; "+
 					"command -v pnpm >/dev/null 2>&1 || npm i -g pnpm; "+
+					// Point pnpm at the shared store volume so installs after the
+					// first reuse downloaded packages instead of re-fetching.
+					"pnpm config set store-dir /pnpm-store 2>/dev/null || true; "+
 					"pnpm config set verify-deps-before-run false; "+
-					"pnpm install || true; pnpm rebuild"),
-			DevCmd: envOr("FASTCLAW_SHIPANY_DEV", "pnpm dev --host 0.0.0.0 --port 3000"),
+					"pnpm install || true; pnpm rebuild; "+
+					// Snapshot the pristine template as a git baseline so the UI
+					// can later show ONLY the files the agent changed (git status
+					// vs this commit). .gitignore already excludes node_modules /
+					// build output, so the diff stays clean.
+					"git config --global --add safe.directory '*' 2>/dev/null || true; "+
+					"git init -q 2>/dev/null || true; git add -A 2>/dev/null || true; "+
+					"git -c user.email=bot@fastclaw -c user.name=fastclaw commit -q -m baseline 2>/dev/null || true"),
+			// Self-heal pnpm before running: the base image ships node+npm
+			// only, and pnpm is installed globally (container FS, NOT the
+			// bind-mounted /workspace). On a wake/re-up the container is
+			// recreated but the workspace already has files, so scaffold is
+			// skipped and the global pnpm is gone — `pnpm dev` would then
+			// fail "pnpm: not found". Ensuring it here makes DevCmd robust
+			// across container recreation without re-running the scaffold.
+			// Self-heal pnpm + its run-time config before starting dev. Both
+			// live in the container FS (global pnpm install + ~/.pnpmrc), NOT
+			// the bind-mounted /workspace, so a wake/re-up that recreates the
+			// container loses them while scaffold is skipped (workspace
+			// non-empty). Without `verify-deps-before-run false`, pnpm 11
+			// re-runs a deps-status check before `dev` that fails against the
+			// volume-mounted node_modules and aborts the server.
+			// Self-heal pnpm, its config, AND deps before dev. All three live
+			// outside the bind-mounted /workspace (global pnpm in container
+			// FS; node_modules in a per-scope volume that Stop removes), so a
+			// re-up after Stop recreates the container with files present
+			// (scaffold skipped) but no deps — `pnpm dev` would then die with
+			// "vite: not found". Reinstalling when node_modules/.bin/vite is
+			// missing makes every boot self-correct (fast: the shared pnpm
+			// store volume hard-links, no re-download).
+			DevCmd: envOr("FASTCLAW_SHIPANY_DEV",
+				"command -v pnpm >/dev/null 2>&1 || npm i -g pnpm; "+
+					"pnpm config set verify-deps-before-run false 2>/dev/null || true; "+
+					"[ -x node_modules/.bin/vite ] || pnpm install || true; "+
+					"pnpm dev --host 0.0.0.0 --port 3000"),
 			// Local template checkout bind-mounted at /template (option C):
 			// set FASTCLAW_SHIPANY_TEMPLATE_DIR=~/code/shipany-tanstack to
 			// scaffold from disk without baking the image or cloning.
 			TemplateMount: os.Getenv("FASTCLAW_SHIPANY_TEMPLATE_DIR"),
 		})
+		// A second, lighter template demonstrating multi-template support:
+		// a plain Vite + React + TS starter. It needs no baked /template and
+		// no R2 source — it self-scaffolds with `npm create vite` — and shares
+		// the SAME sandbox image as shipany (Node toolchain), so it proves the
+		// "one e2b image, many templates differing only by ScaffoldCmd" model
+		// (no per-template image needed for same-stack templates). Vite's HMR
+		// client follows the page origin, so it works through both docker's
+		// host-port map and e2b's <port>-<id>.e2b.app proxy with no extra
+		// config. shipany-tanstack above is untouched.
+		rtMgr.RegisterTemplate("vite-react", coderuntime.TemplateSpec{
+			DevPort: 5173,
+			ScaffoldCmd: envOr("FASTCLAW_VITE_REACT_SCAFFOLD",
+				"set -e; cd /workspace; "+
+					"if [ ! -f package.json ]; then "+
+					"npm create vite@latest .fctmp -- --template react-ts && "+
+					"cp -a .fctmp/. ./ && rm -rf .fctmp; fi; "+
+					"npm install; "+
+					// Git baseline so the UI's changed-files view diffs against
+					// the pristine scaffold — same pattern as shipany above.
+					"git config --global --add safe.directory '*' 2>/dev/null || true; "+
+					"git init -q 2>/dev/null || true; git add -A 2>/dev/null || true; "+
+					"git -c user.email=bot@fastclaw -c user.name=fastclaw commit -q -m baseline 2>/dev/null || true"),
+			DevCmd: envOr("FASTCLAW_VITE_REACT_DEV",
+				"[ -x node_modules/.bin/vite ] || npm install; "+
+					"npm run dev -- --host 0.0.0.0 --port 5173"),
+		})
 		webSrv.SetRuntimeManager(rtMgr) // HTTP /runtime endpoints
 		gw.SetProjectRuntime(rtMgr)     // agent preview tools
 		slog.Info("project runtime enabled",

docs/coding-agent-runtime.md

@@ -145,7 +145,57 @@ Template commands are env-overridable so fastclaw stays template-agnostic:
 
 To add another template (e.g. a Next.js starter), call
 `rtMgr.RegisterTemplate("my-template", coderuntime.TemplateSpec{…})` —
-nothing in the runtime is ShipAny-specific.
+nothing in the runtime is ShipAny-specific. The **first** registered ref is
+the default the preview tool uses when the agent omits one, so registering
+more templates never changes an existing deployment's default. A second
+template ships out of the box — `vite-react`, a plain Vite + React + TS
+starter that self-scaffolds with `npm create vite` (no baked `/template`, no
+source fetch) — as a worked example of multi-template support.
+
+## Sandbox backends (docker vs e2b/boxlite)
+
+The preview path depends on `FASTCLAW_SANDBOX_BACKEND`:
+
+- **docker (default)** — the runtime owns a dedicated long-lived container
+  per project, publishes the dev port to a host port, and the agent's edits
+  reach the dev server through a shared host bind mount. Unchanged.
+- **e2b / boxlite (cloud, no host mount)** — the runtime runs the dev server
+  inside the **same pooled sandbox the agent writes files to** (so HMR works
+  with no bind mount) and exposes the port via the backend's own URL scheme
+  (e2b: `https://<port>-<sandboxID>.e2b.app`). Coding writes route to
+  `workspace.Store`; for a remote-workspace backend they're additionally
+  mirrored into the live sandbox so the dev server sees them.
+
+### Cloud template provisioning (where `/template` comes from)
+
+The scaffold needs the template source at `/template` in the sandbox. On a
+cloud backend there is no host bind mount, so pick one of:
+
+1. **Bake into the sandbox image / e2b template (recommended).** Build the
+   e2b template (or docker image) with the toolchain (node/pnpm + camoufox
+   for copyweb) **and** the template at `/template` — ideally with a warm
+   pnpm store so scaffold installs offline and fast. Rebuild only when deps
+   change. Set the e2b template id via the `e2bTemplate` setting (falls back
+   to `FASTCLAW_SANDBOX_IMAGE`).
+2. **Pull source at scaffold time (image stays stable).** Override
+   `FASTCLAW_SHIPANY_SCAFFOLD` to `curl` a pinned tarball from object storage
+   (R2/S3, via a short-lived presigned URL — no long-lived creds in a sandbox
+   that runs LLM code) into `/workspace`, then `pnpm install --offline`
+   against a warm store baked in the image. Decouples template content from
+   the image; only dep changes need an image rebuild. Prefer this over
+   `git clone` for private templates (no token to exfiltrate, pinned snapshot).
+3. **Upload from the fastclaw host.** When `FASTCLAW_SHIPANY_TEMPLATE_DIR`
+   points at a checkout on the fastclaw server, the e2b path uploads it into
+   the sandbox `/template` (`TemplateProvisioner.ProvisionDir`). Convenient
+   for local e2b testing; costs a per-cold-sandbox upload.
+
+**Multi-template, one image:** same-stack templates (e.g. several ShipAny
+variants) share ONE backend image and differ only by `ScaffoldCmd` / source —
+you do **not** need an e2b image per template. A genuinely different stack
+(Python vs Node) is the only reason to vary the image; `TemplateSpec.Image`
+pins a per-template image on the **docker** path (the e2b path uses the one
+pool image, so per-template e2b images would need a pool per-project override
+— not wired yet).
 
 ### Sandbox image requirements
 

internal/agent/context.go

@@ -321,7 +321,11 @@ func (cb *ContextBuilder) BuildSystemPromptAs(chatterUID string, chatterMem *Mem
 	loc := cb.chatterLocation(chatterUID)
 	now := time.Now().In(loc)
 	wd := now.Weekday().String()
-	dateLine := fmt.Sprintf("Current date/time: %s (%s, %s — the chatter's local timezone). Use this — do NOT call `date` to learn what day it is.",
+	dateLine := fmt.Sprintf("Current date/time: %s (%s, %s — the chatter's local timezone). This is NOW; do NOT call `date`. "+
+		"Each past user message in the history is prefixed with its own send time in [brackets] (e.g. [2026-06-13 22:15 Fri]). "+
+		"Reason about time from NOW and those prefixes: tell today apart from earlier days (never treat a past day's events as today's), "+
+		"and before ANY time-of-day remark check NOW — e.g. don't say \"good night\" in the middle of the day. "+
+		"If the chatter states a timezone or local time that disagrees with the above, call set_timezone to correct it.",
 		now.Format("2006-01-02 15:04:05 -0700"), wd, now.Location().String())
 
 	switch mode {

internal/agent/loop.go

@@ -1668,7 +1668,7 @@ func (a *Agent) handlePlanMode(ctx context.Context, msg bus.InboundMessage) stri
 	if catalog != "" {
 		messages = append(messages, provider.Message{Role: "system", Content: catalog})
 	}
-	messages = append(messages, sess.GetMessages()...)
+	messages = append(messages, a.withMessageTimestamps(sess.GetMessages())...)
 	if a.piiScrubEnabled {
 		messages = privacy.ScrubMessages(messages)
 	}
@@ -1905,7 +1905,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 	if reminder := renderChatbotPersistenceReminder(a.promptMode, a.displayName, chatterMem.LoadUserFile(), chatterMem.LoadMemory()); reminder != "" {
 		messages = append(messages, provider.Message{Role: "system", Content: reminder})
 	}
-	messages = append(messages, sessionMsgs...)
+	messages = append(messages, a.withMessageTimestamps(sessionMsgs)...)
 
 	toolDefs := a.registry.DefinitionsForMode(builtinAllowForMode(a.promptMode))
 
@@ -2601,7 +2601,7 @@ func (a *Agent) HandleMessageStream(ctx context.Context, msg bus.InboundMessage)
 	if reminder := renderChatbotPersistenceReminder(a.promptMode, a.displayName, chatterMem.LoadUserFile(), chatterMem.LoadMemory()); reminder != "" {
 		messages = append(messages, provider.Message{Role: "system", Content: reminder})
 	}
-	messages = append(messages, sessionMsgs...)
+	messages = append(messages, a.withMessageTimestamps(sessionMsgs)...)
 
 	toolDefs := a.registry.DefinitionsForMode(builtinAllowForMode(a.promptMode))
 
@@ -3063,6 +3063,30 @@ func (a *Agent) chatterLocation(chatterUID string) *time.Location {
 	return scope.LoadLocationOrLocal(tz)
 }
 
+// withMessageTimestamps returns a COPY of msgs where each user message is
+// prefixed with its send time in the chatter's timezone, e.g.
+// "[2026-06-13 22:15 Fri] …". This is what lets the model reason about
+// time across a conversation — tell today from earlier days, and not say
+// "good night" at midday. The originals are never mutated (the prefix is
+// a read-time view for the LLM, not stored history), so the session store
+// stays clean and the next turn doesn't double-prefix. The system prompt
+// (context.go dateLine) tells the model what the bracketed prefix means.
+func (a *Agent) withMessageTimestamps(msgs []provider.Message) []provider.Message {
+	if len(msgs) == 0 {
+		return msgs
+	}
+	loc := a.chatterLocation(a.registry.ChatterUserID())
+	out := make([]provider.Message, len(msgs))
+	for i, m := range msgs {
+		if m.Role == "user" && m.Timestamp > 0 && m.Content != "" {
+			t := time.UnixMilli(m.Timestamp).In(loc)
+			m.Content = "[" + t.Format("2006-01-02 15:04 Mon") + "] " + m.Content
+		}
+		out[i] = m
+	}
+	return out
+}
+
 // UpdateConfig updates the agent's runtime config (model, temperature, etc.)
 func (a *Agent) UpdateConfig(rc config.ResolvedAgent) {
 	a.model = rc.Model

internal/agent/runtime_tools.go

@@ -29,6 +29,15 @@ func (a *Agent) SetProjectRuntime(m *coderuntime.Manager) {
 func (a *Agent) registerProjectRuntimeTools() {
 	reg := a.registry
 
+	// Surface the registered templates so the model can pick one by name
+	// (and knows the default). Built at registration time — the manager has
+	// every RegisterTemplate applied before SetProjectRuntime runs.
+	tmplDesc := "Template ref to scaffold from on first boot (e.g. \"shipany-tanstack\"). Optional once a runtime already exists; the deployment's default is used when omitted."
+	if refs := a.projectRuntime.Templates(); len(refs) > 0 {
+		tmplDesc = fmt.Sprintf("Template ref to scaffold from on first boot. Available: %s — the first is the default, used when omitted. Optional once a runtime already exists.",
+			strings.Join(refs, ", "))
+	}
+
 	reg.Register(
 		"start_app_preview",
 		"PRIMARY tool for building a web app / website / landing page / dashboard — INCLUDING requests like 'use template X to make Y' or '用某模板做个…'. "+
@@ -40,7 +49,7 @@ func (a *Agent) registerProjectRuntimeTools() {
 			"properties": map[string]any{
 				"template": map[string]any{
 					"type":        "string",
-					"description": "Template ref to scaffold from on first boot (e.g. \"shipany-tanstack\"). Optional once a runtime already exists; the deployment's default is used when omitted.",
+					"description": tmplDesc,
 				},
 			},
 		},

internal/agent/tools/file.go

@@ -863,6 +863,29 @@ func makeListDir(r *Registry) ToolFunc {
 // the path (absolute paths, `skills/...`, ad-hoc scripts, etc.). The
 // sandbox badge is emitted only for the executor-fallback path — store
 // hits intentionally don't badge, since they didn't run in the sandbox.
+// mirrorCodingWriteToSandbox pushes a coding-agent workspace write into the
+// live preview sandbox. Coding writes route to workspace.Store (host), which
+// docker bind-mounts into the dev-server container — but a remote backend
+// (E2B) shares no host mount, so without this the dev server never sees the
+// edit and HMR looks dead. Guarded on RemoteWorkspace, so it's a no-op for
+// docker (whose executor isn't remote). Best-effort: the user-visible write
+// already hit the store, so a mirror failure only degrades live-reload — we
+// log and move on. Destination is ABSOLUTE /workspace/<path> because the
+// dev server serves the sandbox /workspace root and envd resolves a bare
+// path against $HOME, not /workspace.
+func (r *Registry) mirrorCodingWriteToSandbox(ctx context.Context, path, content string) {
+	if r.codingSubdir == "" || r.executor == nil {
+		return
+	}
+	if _, ok := r.executor.(sandbox.RemoteWorkspace); !ok {
+		return
+	}
+	dest := "/workspace/" + strings.TrimPrefix(filepath.ToSlash(filepath.Clean(path)), "/")
+	if _, err := r.executor.WriteFile(ctx, dest, content); err != nil {
+		slog.Warn("coding preview mirror to sandbox failed", "path", dest, "err", err)
+	}
+}
+
 func registerSandboxedFile(r *Registry, ex sandbox.Executor) {
 	r.Register("read_file", "Read the contents of a file", map[string]interface{}{
 		"type": "object",
@@ -995,6 +1018,7 @@ func registerSandboxedFile(r *Registry, ex sandbox.Executor) {
 				}
 				return "", fmt.Errorf("workspace put: %w", err)
 			}
+			r.mirrorCodingWriteToSandbox(ctx, args.Path, args.Content)
 			return fmt.Sprintf("Written %d bytes to %s", len(args.Content), args.Path), nil
 		case RouteSkillStore:
 			// Skill scaffolding (skill-creator's `skills/<name>/...`) lands
@@ -1175,6 +1199,7 @@ func registerSandboxedFile(r *Registry, ex sandbox.Executor) {
 						}
 						return "", fmt.Errorf("workspace put: %w", err)
 					}
+					r.mirrorCodingWriteToSandbox(ctx, args.Path, updated)
 					return fmt.Sprintf("Edited %s (%d replacement(s))", args.Path, count), nil
 				}
 			}

internal/gateway/gateway.go

@@ -226,6 +226,13 @@ func (g *Gateway) Usage() usage.Meter { return g.usage }
 // Store returns the gateway's storage backend.
 func (g *Gateway) Store() store.Store { return g.store }
 
+// SandboxPool returns the gateway's shared system sandbox pool (nil when
+// sandboxing is disabled). The project runtime borrows it so a dev-server
+// preview runs in the SAME executor the coding agent writes files to —
+// the only way edits reach the server on backends (E2B) without a shared
+// host mount.
+func (g *Gateway) SandboxPool() sandbox.ExecutorPool { return g.sandboxPool }
+
 // TaskQueue returns the gateway's task queue.
 func (g *Gateway) TaskQueue() *taskqueue.Queue { return g.taskQueue }