@swarmclawai/swarmclaw 1.5.58 → 1.5.60

package/README.md

@@ -399,6 +399,22 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.60 Highlights
+
+Adds a turn-snapshot primitive for external replay and comparison tooling, without touching the execution flow.
+
+- **Turn snapshot endpoint.** New `GET /api/chats/:id/turns/:index/snapshot` returns the input state of a prior user turn: the message (text + optional imagePath + time), all prior messages in order, the session's effective provider/model/endpoint/credential at snapshot time, and the bound agent's provider/model/systemPrompt when available. Invalid or non-user indices return `400`, out-of-range indices return `404`. CLI: `swarmclaw chats turn-snapshot <chatId> <index>`.
+- **Use case.** External CLIs, notebooks, and comparison harnesses can now capture the exact inputs that produced a given turn and replay them against a different model, provider, or system prompt to compare outputs — without mutating the original session. Pairs with the existing `edit-resend` path (destructive in-session replay) and the new share-link infrastructure in v1.5.59 (share the original turn's context, replay on another instance).
+
+### v1.5.59 Highlights
+
+Viral-loop release. Adds public share links for missions, skills, and sessions, plus a complementary raw-markdown endpoint so any shared skill installs directly through the existing `POST /api/skills/import`.
+
+- **Share links for missions, skills, and sessions.** New `share_links` collection in `src/lib/server/storage.ts` plus `src/lib/server/sharing/share-link-repository.ts`. `POST /api/share { entityType, entityId, expiresInSec?, label? }` mints a cryptographically random 32-char base64url token; `GET /api/share` lists; `GET /api/share/:id` fetches; `DELETE /api/share/:id` revokes (pass `?hard=true` to hard-delete). CLI: `swarmclaw share {list,mint,get,revoke,resolve,raw}`.
+- **Public read endpoints (no auth required).** `GET /api/s/:token` returns the scrubbed JSON payload; `GET /api/s/:token/raw` returns plain markdown (skills return their SKILL.md verbatim, missions render as title + goal + criteria + milestones, sessions as a transcript). Revoked and expired tokens return `404 Not found` without leaking shape information. `GET /s/:token` is a server-rendered page for dropping straight into a browser.
+- **Share-link-based skill install.** `POST /api/skills/import` already accepts an http(s) URL; pointing it at `https://<your-host>/api/s/<token>/raw` now installs a shared skill from another SwarmClaw instance without auth handshakes. Pairs naturally with existing `swarmclaw skills import` CLI.
+- **Share-link repository tests.** `share-link-repository.test.ts` covers mint / list / revoke / lookup-by-token round-trip plus expiry handling against a temporary data dir.
+
 ### v1.5.58 Highlights
 
 This release broadens the built-in evaluation harness so SwarmClaw runs can be benchmarked against named suites, adds two targeted starter kits, exposes live per-session cost data, tightens auto-skill drafting, and ships a zero-setup demo mission template.
@@ -428,24 +444,6 @@ This release closes the org-orchestration feature gap with Paperclip while keepi
 - **Fix: TTS error responses are now proper JSON instead of a raw Buffer blob.** `POST /api/tts` and `POST /api/tts/stream` previously returned `500` with the error message wrapped in a `new NextResponse(string, ...)` that the CLI JSON-decoded into `{"type":"Buffer","data":[78,111,...]}`. Both routes now return `NextResponse.json({error}, {status: 500})`. Regression test added.
 - **Zod-validated PUT/PATCH endpoints — hardening sweep.** Extends the v1.5.55 work (agents, tasks, webhooks) to close the same silent-corruption bug class on the remaining vulnerable routes: `PUT /api/secrets/:id`, `POST /api/secrets`, `PATCH /api/goals/:id`, `PUT /api/providers/:id`, `PUT /api/documents/:id`, `PUT /api/external-agents/:id`, and `PUT /api/chatrooms/:id`. Each route validates against a dedicated schema (`SecretUpdateSchema`, `SecretCreateSchema`, `GoalUpdateSchema`, `ProviderUpdateSchema`, `DocumentUpdateSchema`, `ExternalAgentUpdateSchema`, `ChatroomUpdateSchema`) in `src/lib/validation/schemas.ts`, then filters parsed data to the keys actually present in the raw body so Zod defaults can't overwrite untouched stored fields. Endpoints already doing per-field `typeof` guards (knowledge, gateways, projects) were left as-is.
 
-### v1.5.55 Highlights
-
-- **Fix: mission budget updates with decimal values no longer silently fail with a 400.** The mission UI's `numOrNull` parsed user input with `Number.parseFloat`, but the API requires `int()` for `maxTokens`, `maxToolCalls`, `maxWallclockSec`, and `maxTurns`. Typing `1000.5` returned a cryptic Zod error to the toast and the update was lost. Added `intOrNull` (rounds) in `mission-edit-sheet.tsx`, `mission-template-install-dialog.tsx`, and `app/missions/page.tsx`. `maxUsd` still accepts decimals.
-- **Fix: mission edit sheet's connectors dropdown was always empty.** The sheet fetched `/connectors` expecting a `Connector[]`, but the endpoint returns `Record<string, Connector>`. The defensive `Array.isArray` fallback quietly rendered an empty list, so users could not attach report connectors when editing a running mission. Now typed as `Record<string, Connector>` and projected with `Object.values`.
-- **Fix: memory search returns results for short (3-4 char) words like `cats`, `blue`, `dog`.** `buildFtsQuery` had a `unique[0].length >= 5` guard that returned an empty FTS query for any single-token search shorter than 5 chars, silently dropping valid searches. The upstream filter already requires ≥3 chars, so the extra guard just excluded useful queries. Removed; regression tests cover `cats`, `blue`, and `dog`.
-- **Fix: `PUT /api/agents/:id` now validates its body with a Zod schema.** Previously the route did `{...current, ...body}` without validation, so sending `{"tools": "not_an_array"}` silently wiped the agent's tool list to `[]`. Added `AgentUpdateSchema = AgentCreateSchema.partial()` and a filter step that keeps only keys present in the raw body (so Zod defaults do not overwrite untouched fields). Bad types now return a 400 with field-level errors. `updateAgent()` keeps a `current.tools` / `current.extensions` fallback as defense-in-depth for internal callers.
-- **Fix: `PUT /api/tasks/:id` now validates its body with a Zod schema.** Same class of bug: a numeric `title` silently corrupted the stored field. Added `TaskUpdateSchema = TaskCreateSchema.partial().extend({...})` with the update-only fields (`appendComment`, `result`, `error`, lifecycle timestamps) and the same raw-key filter pattern. Bad types now 400 with untouched storage.
-- **Fix: `PUT /api/webhooks/:id` now validates its body with a Zod schema.** Previously `{"events": "not_an_array"}` wiped the events list. Added `WebhookUpdateSchema` and explicit `rawKeys.has(...)` guards in the mutate closure so only fields actually present in the body are applied.
-- **Fix: classifier JSON no longer leaks into assistant responses.** Some Ollama / Ollama Cloud turns were emitting the internal `MessageClassification` object directly into the stream (e.g. `{"taskIntent":"research",...}` prepended to the real reply). The existing stripper only matched when `isDeliverableTask` was the first key, so leaks starting with `taskIntent` sailed through to the user. Replaced the regex with a principled detector that brace-matches candidate JSON (string-quote aware) and validates against `MessageClassificationSchema.safeParse` — the schema itself is the source of truth, so future schema changes can't break detection.
-
-### v1.5.54 Highlights
-
-- **Mission templates library**: the `/missions` page now opens with a curated gallery of starter missions. Each template pre-wires a goal, success criteria, USD / token / turn / wallclock budgets, and a report cadence, so non-technical users can install a working autonomous run in one click. Initial lineup: Daily News Digest, Inbox Triage, Competitor Watch, Weekly Research Report, Social Listener, and Customer Support Triage. Setup notes flag any connector or permission prerequisites before installation. Power-user overrides (budget caps, success criteria, report cadence) live behind a collapsed **Advanced Settings** panel so the default install flow stays one click.
-- **New API routes `GET /api/missions/templates` and `POST /api/missions/templates/:id/instantiate`** with matching CLI commands `swarmclaw missions templates` and `swarmclaw missions instantiate`. Installed missions persist a `templateId` so the origin is traceable for future template-update flows; legacy missions normalize to `templateId: null` on load, no data migration required.
-- **Fix: user-selected provider and model now survive the chat execution pipeline** ([#51](https://github.com/swarmclawai/swarmclaw/pull/51), thanks to [@borislavnnikolov](https://github.com/borislavnnikolov)). Switching provider or model via the inspector panel mid-session was being reverted on every turn because the agent's configured route was unconditionally reapplied in three places. `syncSessionFromAgent` now only syncs credentials / endpoint / fallbacks when the session's provider still matches the route provider, `prepareChatTurn` preserves the user's chosen model after applying the route, and `updateChatSession` auto-resolves a stored credential for the new provider (and clears the stale `apiEndpoint`) when provider changes without an explicit `credentialId`. Restores reliable switching between Copilot CLI, Codex CLI, Groq, and OpenAI-compatible providers.
-
-> **Note:** v1.5.53 release notes described the mission templates library, but the feature commit landed after the v1.5.53 tag was cut. v1.5.54 is the release that actually ships it.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.58",
+  "version": "1.5.60",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/chats/[id]/turns/[index]/snapshot/route.ts

@@ -0,0 +1,90 @@
+import { NextResponse } from 'next/server'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { getMessages } from '@/lib/server/messages/message-repository'
+import { loadAgent } from '@/lib/server/agents/agent-repository'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Turn snapshot — returns the input state of the turn at :index so external
+ * tools (CLIs, notebooks, comparison harnesses) can replay the same turn
+ * against a different model, provider, or system prompt without mutating
+ * the original session.
+ *
+ * Shape is intentionally minimal and stable:
+ *  - `userMessage`: the message that opened the turn (text + optional imagePath)
+ *  - `priorMessages`: everything before that turn, in order
+ *  - `route`: the session's effective provider/model/endpoint at snapshot time
+ *  - `agent`: the agent's provider/model/systemPrompt (if bound), for reference
+ */
+export async function GET(
+  _req: Request,
+  ctx: { params: Promise<{ id: string; index: string }> },
+) {
+  const { id, index } = await ctx.params
+  const session = getSession(id)
+  if (!session) {
+    return NextResponse.json({ error: 'session_not_found' }, { status: 404 })
+  }
+
+  const i = Number.parseInt(index, 10)
+  if (!Number.isInteger(i) || i < 0) {
+    return NextResponse.json({ error: 'invalid_index' }, { status: 400 })
+  }
+
+  const messages = getMessages(id)
+  if (i >= messages.length) {
+    return NextResponse.json({ error: 'index_out_of_range' }, { status: 404 })
+  }
+
+  const target = messages[i]
+  if (!target || target.role !== 'user') {
+    return NextResponse.json({ error: 'not_a_user_turn' }, { status: 400 })
+  }
+
+  const priorMessages = messages.slice(0, i).map((m) => ({
+    role: m.role,
+    text: m.text || '',
+    at: typeof m.time === 'number' ? m.time : null,
+  }))
+
+  const userMessage = {
+    text: target.text || '',
+    imagePath: target.imagePath || null,
+    at: typeof target.time === 'number' ? target.time : null,
+  }
+
+  const route = {
+    provider: session.provider ?? null,
+    model: session.model ?? null,
+    apiEndpoint: session.apiEndpoint ?? null,
+    credentialId: session.credentialId ?? null,
+  }
+
+  let agent: null | {
+    id: string
+    provider: string | null
+    model: string | null
+    systemPrompt: string | null
+  } = null
+  if (session.agentId) {
+    const a = loadAgent(session.agentId)
+    if (a) {
+      agent = {
+        id: a.id,
+        provider: (a.provider as string) ?? null,
+        model: (a.model as string) ?? null,
+        systemPrompt: typeof a.systemPrompt === 'string' ? a.systemPrompt : null,
+      }
+    }
+  }
+
+  return NextResponse.json({
+    sessionId: id,
+    index: i,
+    userMessage,
+    priorMessages,
+    route,
+    agent,
+  })
+}

package/src/app/api/s/[token]/raw/route.ts

@@ -0,0 +1,79 @@
+import {
+  isShareLinkActive,
+  loadShareLinkByToken,
+} from '@/lib/server/sharing/share-link-repository'
+import { resolveSharedEntity } from '@/lib/server/sharing/share-resolver'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Public raw-content endpoint for shared entities. Skills return markdown so
+ * a second SwarmClaw instance can install via `POST /api/skills/import`
+ * without any auth handshake. Missions and sessions return plain-text
+ * summaries sized for quick sharing.
+ *
+ * Returns 404 for missing, expired, or revoked tokens to avoid leaking
+ * shape information to a probe.
+ */
+export async function GET(_req: Request, ctx: { params: Promise<{ token: string }> }) {
+  const { token } = await ctx.params
+  const link = loadShareLinkByToken(token)
+  if (!link || !isShareLinkActive(link)) {
+    return new Response('Not found', { status: 404 })
+  }
+  const payload = resolveSharedEntity(link)
+  if (!payload) {
+    return new Response('Not found', { status: 404 })
+  }
+
+  if (payload.kind === 'skill') {
+    return new Response(payload.content, {
+      status: 200,
+      headers: {
+        'content-type': 'text/markdown; charset=utf-8',
+        'cache-control': 'public, max-age=60',
+        'x-skill-name': encodeURIComponent(payload.name),
+      },
+    })
+  }
+
+  if (payload.kind === 'mission') {
+    const lines: string[] = []
+    lines.push(`# ${payload.title}`, '')
+    if (payload.goal) lines.push(payload.goal, '')
+    if (payload.successCriteria.length > 0) {
+      lines.push('## Success criteria', '')
+      for (const c of payload.successCriteria) lines.push(`- ${c}`)
+      lines.push('')
+    }
+    if (payload.milestones.length > 0) {
+      lines.push('## Milestones', '')
+      for (const m of payload.milestones) {
+        lines.push(`- ${new Date(m.at).toISOString().slice(0, 19).replace('T', ' ')}: ${m.note}`)
+      }
+      lines.push('')
+    }
+    return new Response(lines.join('\n'), {
+      status: 200,
+      headers: {
+        'content-type': 'text/markdown; charset=utf-8',
+        'cache-control': 'public, max-age=60',
+      },
+    })
+  }
+
+  // session
+  const lines: string[] = []
+  lines.push(`# ${payload.name}`, '')
+  if (payload.agentName) lines.push(`Agent: ${payload.agentName}`, '')
+  for (const m of payload.messages) {
+    lines.push(`### ${m.role}`, '', m.text, '')
+  }
+  return new Response(lines.join('\n'), {
+    status: 200,
+    headers: {
+      'content-type': 'text/markdown; charset=utf-8',
+      'cache-control': 'public, max-age=60',
+    },
+  })
+}

package/src/app/api/s/[token]/route.ts

@@ -0,0 +1,37 @@
+import { NextResponse } from 'next/server'
+import {
+  isShareLinkActive,
+  loadShareLinkByToken,
+} from '@/lib/server/sharing/share-link-repository'
+import { resolveSharedEntity } from '@/lib/server/sharing/share-resolver'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Public, unauthenticated fetch of a shared entity by token.
+ *
+ * Returns the scrubbed payload shape (secrets and credentials are never
+ * loaded into the resolver). A 404 is returned for unknown, expired, or
+ * revoked tokens to avoid leaking validity to a probe.
+ */
+export async function GET(_req: Request, ctx: { params: Promise<{ token: string }> }) {
+  const { token } = await ctx.params
+  const link = loadShareLinkByToken(token)
+  if (!link || !isShareLinkActive(link)) {
+    return NextResponse.json({ error: 'not_found' }, { status: 404 })
+  }
+  const payload = resolveSharedEntity(link)
+  if (!payload) {
+    return NextResponse.json({ error: 'entity_missing' }, { status: 404 })
+  }
+  return NextResponse.json({
+    share: {
+      id: link.id,
+      entityType: link.entityType,
+      label: link.label,
+      createdAt: link.createdAt,
+      expiresAt: link.expiresAt,
+    },
+    payload,
+  })
+}

package/src/app/api/share/[id]/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server'
+import {
+  loadShareLinkById,
+  revokeShareLink,
+  deleteShareLink,
+} from '@/lib/server/sharing/share-link-repository'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(_req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params
+  const link = loadShareLinkById(id)
+  if (!link) return NextResponse.json({ error: 'not_found' }, { status: 404 })
+  return NextResponse.json(link)
+}
+
+export async function DELETE(req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params
+  const { searchParams } = new URL(req.url)
+  const hard = searchParams.get('hard') === 'true'
+  if (hard) {
+    deleteShareLink(id)
+    return NextResponse.json({ ok: true, deleted: true })
+  }
+  const revoked = revokeShareLink(id)
+  if (!revoked) return NextResponse.json({ error: 'not_found' }, { status: 404 })
+  return NextResponse.json(revoked)
+}

package/src/app/api/share/route.ts

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import {
+  createShareLink,
+  listShareLinks,
+  type ShareEntityType,
+} from '@/lib/server/sharing/share-link-repository'
+import { errorMessage } from '@/lib/shared-utils'
+
+export const dynamic = 'force-dynamic'
+
+const MintSchema = z.object({
+  entityType: z.enum(['mission', 'skill', 'session']),
+  entityId: z.string().min(1),
+  expiresInSec: z.number().int().positive().nullable().optional(),
+  label: z.string().trim().max(120).nullable().optional(),
+})
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const entityType = searchParams.get('entityType') as ShareEntityType | null
+  const entityId = searchParams.get('entityId')
+
+  let links = listShareLinks()
+  if (entityType) links = links.filter((l) => l.entityType === entityType)
+  if (entityId) links = links.filter((l) => l.entityId === entityId)
+
+  // Newest first
+  links.sort((a, b) => b.createdAt - a.createdAt)
+  return NextResponse.json(links)
+}
+
+export async function POST(req: Request) {
+  try {
+    const body: unknown = await req.json()
+    const parsed = MintSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: parsed.error.issues.map((i) => i.message).join(', ') },
+        { status: 400 },
+      )
+    }
+    const link = createShareLink({
+      entityType: parsed.data.entityType,
+      entityId: parsed.data.entityId,
+      expiresInSec: parsed.data.expiresInSec ?? null,
+      label: parsed.data.label ?? null,
+    })
+    return NextResponse.json(link)
+  } catch (err) {
+    return NextResponse.json({ error: errorMessage(err) }, { status: 500 })
+  }
+}

package/src/app/s/[token]/page.tsx

@@ -0,0 +1,138 @@
+import { notFound } from 'next/navigation'
+import {
+  isShareLinkActive,
+  loadShareLinkByToken,
+} from '@/lib/server/sharing/share-link-repository'
+import { resolveSharedEntity, type SharedPayload } from '@/lib/server/sharing/share-resolver'
+
+export const dynamic = 'force-dynamic'
+
+export default async function SharedEntityPage({
+  params,
+}: {
+  params: Promise<{ token: string }>
+}) {
+  const { token } = await params
+  const link = loadShareLinkByToken(token)
+  if (!link || !isShareLinkActive(link)) notFound()
+  const payload = resolveSharedEntity(link)
+  if (!payload) notFound()
+
+  return (
+    <div className="mx-auto max-w-3xl px-6 py-10 font-sans">
+      <header className="mb-8">
+        <div className="text-xs uppercase tracking-wider text-neutral-500">
+          Shared {payload.kind}
+        </div>
+        {link.label ? (
+          <h1 className="mt-1 text-2xl font-semibold">{link.label}</h1>
+        ) : null}
+      </header>
+      {renderBody(payload)}
+      <footer className="mt-10 border-t border-neutral-200 pt-4 text-xs text-neutral-500">
+        Public share link. Secrets and credentials are omitted.
+      </footer>
+    </div>
+  )
+}
+
+function renderBody(payload: SharedPayload) {
+  if (payload.kind === 'mission') {
+    return (
+      <section>
+        <h2 className="text-xl font-semibold">{payload.title}</h2>
+        <p className="mt-3 whitespace-pre-wrap text-neutral-800">{payload.goal}</p>
+        {payload.successCriteria.length > 0 ? (
+          <>
+            <h3 className="mt-6 font-semibold">Success criteria</h3>
+            <ul className="mt-2 list-disc pl-6 text-neutral-800">
+              {payload.successCriteria.map((c, i) => (
+                <li key={i}>{c}</li>
+              ))}
+            </ul>
+          </>
+        ) : null}
+        {payload.milestones.length > 0 ? (
+          <>
+            <h3 className="mt-6 font-semibold">Milestones</h3>
+            <ol className="mt-2 space-y-1 text-sm text-neutral-800">
+              {payload.milestones.map((m, i) => (
+                <li key={i}>
+                  <span className="text-neutral-500">{formatTime(m.at)}:</span> {m.note}
+                </li>
+              ))}
+            </ol>
+          </>
+        ) : null}
+        {payload.reports.length > 0 ? (
+          <>
+            <h3 className="mt-6 font-semibold">Reports</h3>
+            <div className="mt-3 space-y-4">
+              {payload.reports.map((r, i) => (
+                <article key={i} className="rounded border border-neutral-200 p-4">
+                  <div className="mb-2 text-xs text-neutral-500">
+                    {formatTime(r.at)} · {r.format}
+                  </div>
+                  <pre className="whitespace-pre-wrap text-sm text-neutral-800">{r.content}</pre>
+                </article>
+              ))}
+            </div>
+          </>
+        ) : null}
+      </section>
+    )
+  }
+
+  if (payload.kind === 'skill') {
+    return (
+      <section>
+        <h2 className="text-xl font-semibold">{payload.name}</h2>
+        {payload.tags.length > 0 ? (
+          <div className="mt-2 flex flex-wrap gap-2">
+            {payload.tags.map((t) => (
+              <span key={t} className="rounded bg-neutral-100 px-2 py-0.5 text-xs text-neutral-700">
+                {t}
+              </span>
+            ))}
+          </div>
+        ) : null}
+        <p className="mt-4 text-neutral-800">{payload.description}</p>
+        <pre className="mt-6 whitespace-pre-wrap rounded border border-neutral-200 bg-neutral-50 p-4 text-sm text-neutral-800">
+          {payload.content}
+        </pre>
+      </section>
+    )
+  }
+
+  return (
+    <section>
+      <h2 className="text-xl font-semibold">{payload.name}</h2>
+      {payload.agentName ? (
+        <div className="mt-1 text-sm text-neutral-500">Agent: {payload.agentName}</div>
+      ) : null}
+      <div className="mt-6 space-y-4">
+        {payload.messages.map((m, i) => (
+          <article
+            key={i}
+            className="rounded border border-neutral-200 p-4"
+          >
+            <div className="mb-1 flex items-center justify-between text-xs text-neutral-500">
+              <span className="uppercase">{m.role}</span>
+              {m.at ? <span>{formatTime(m.at)}</span> : null}
+            </div>
+            <pre className="whitespace-pre-wrap text-sm text-neutral-800">{m.text}</pre>
+          </article>
+        ))}
+      </div>
+    </section>
+  )
+}
+
+function formatTime(ts: number): string {
+  if (!ts) return ''
+  try {
+    return new Date(ts).toISOString().replace('T', ' ').slice(0, 19)
+  } catch {
+    return ''
+  }
+}

package/src/cli/index.js

@@ -579,6 +579,7 @@ const COMMAND_GROUPS = [
       cmd('messages-send', 'POST', '/chats/:id/messages', 'Append a user/system message to a chat', { expectsJsonBody: true }),
       cmd('messages-delete', 'DELETE', '/chats/:id/messages', 'Delete a message from a chat', { expectsJsonBody: true }),
       cmd('edit-resend', 'POST', '/chats/:id/edit-resend', 'Edit and resend from a specific message index', { expectsJsonBody: true }),
+      cmd('turn-snapshot', 'GET', '/chats/:id/turns/:index/snapshot', 'Snapshot the input state of a prior user turn (for external replay)'),
       cmd('chat', 'POST', '/chats/:id/chat', 'Send chat message (streaming)', {
         expectsJsonBody: true,
         responseType: 'sse',
@@ -640,6 +641,18 @@ const COMMAND_GROUPS = [
       cmd('review-counts', 'GET', '/skill-review-counts', 'Show pending review counts'),
     ],
   },
+  {
+    name: 'share',
+    description: 'Public share links for missions, skills, and sessions',
+    commands: [
+      cmd('list', 'GET', '/share', 'List share links (supports --query entityType=mission,entityId=...)'),
+      cmd('mint', 'POST', '/share', 'Mint a new share link', { expectsJsonBody: true }),
+      cmd('get', 'GET', '/share/:id', 'Get a share link by id'),
+      cmd('revoke', 'DELETE', '/share/:id', 'Revoke a share link'),
+      cmd('resolve', 'GET', '/s/:token', 'Resolve a public share token to its scrubbed payload'),
+      cmd('raw', 'GET', '/s/:token/raw', 'Fetch the raw markdown body for a share token (skill/mission/session)'),
+    ],
+  },
   {
     name: 'skills',
     description: 'Manage reusable skills',

package/src/lib/server/sharing/share-link-repository.test.ts

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { test } from 'node:test'
+
+test('share-link-repository: mint / list / revoke / lookup-by-token round-trip', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-share-'))
+  process.env.DATA_DIR = tmpDir
+  process.env.ACCESS_KEY = 'test-key'
+  process.env.CREDENTIAL_SECRET = 'test-secret-32-characters-long!!'
+
+  const {
+    createShareLink,
+    listShareLinks,
+    loadShareLinkById,
+    loadShareLinkByToken,
+    revokeShareLink,
+    isShareLinkActive,
+    deleteShareLink,
+  } = await import('./share-link-repository')
+
+  const a = createShareLink({ entityType: 'mission', entityId: 'mission-1', label: 'hello' })
+  const b = createShareLink({ entityType: 'skill', entityId: 'skill-2', expiresInSec: 60 })
+
+  assert.notEqual(a.token, b.token, 'tokens must be unique')
+  assert.ok(a.token.length >= 16, 'token should be non-trivially long')
+  assert.equal(a.label, 'hello')
+  assert.equal(a.revokedAt, null)
+  assert.equal(a.expiresAt, null)
+  assert.ok(b.expiresAt && b.expiresAt > Date.now(), 'b should have a future expiry')
+
+  const list = listShareLinks()
+  assert.equal(list.length, 2, 'both links should be listed')
+
+  const byTokenA = loadShareLinkByToken(a.token)
+  assert.equal(byTokenA?.id, a.id, 'loadShareLinkByToken finds the link')
+
+  assert.equal(loadShareLinkByToken('not-a-real-token'), null, 'bad token returns null')
+
+  // Before revoke — active
+  assert.equal(isShareLinkActive(a), true)
+
+  const revoked = revokeShareLink(a.id)
+  assert.ok(revoked?.revokedAt, 'revoke stamps a timestamp')
+  assert.equal(isShareLinkActive(revoked!), false, 'revoked link is inactive')
+
+  // Reload from disk — revocation persisted
+  const reloaded = loadShareLinkById(a.id)
+  assert.ok(reloaded?.revokedAt, 'revocation persists across reload')
+
+  // Hard delete
+  deleteShareLink(b.id)
+  assert.equal(loadShareLinkById(b.id), null, 'hard delete removes the record')
+  assert.equal(listShareLinks().length, 1, 'listing drops deleted records')
+})
+
+test('share-link-repository: expired links are inactive', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-share-'))
+  process.env.DATA_DIR = tmpDir
+  process.env.ACCESS_KEY = 'test-key'
+  process.env.CREDENTIAL_SECRET = 'test-secret-32-characters-long!!'
+
+  const { createShareLink, isShareLinkActive } = await import('./share-link-repository')
+
+  const link = createShareLink({ entityType: 'session', entityId: 'sess-1', expiresInSec: 1 })
+  assert.equal(isShareLinkActive(link, Date.now()), true, 'fresh link is active')
+  assert.equal(isShareLinkActive(link, Date.now() + 2000), false, 'past-expiry is inactive')
+})

package/src/lib/server/sharing/share-link-repository.ts

@@ -0,0 +1,107 @@
+import crypto from 'node:crypto'
+import {
+  loadCollection,
+  loadStoredItem,
+  upsertStoredItem,
+  deleteStoredItem,
+} from '@/lib/server/storage'
+import { genId } from '@/lib/id'
+
+export type ShareEntityType = 'mission' | 'skill' | 'session'
+
+export interface ShareLink {
+  id: string
+  token: string
+  entityType: ShareEntityType
+  entityId: string
+  label: string | null
+  createdAt: number
+  expiresAt: number | null
+  revokedAt: number | null
+}
+
+const TOKEN_BYTES = 24 // 32 base64url chars
+
+function generateToken(): string {
+  return crypto.randomBytes(TOKEN_BYTES).toString('base64url')
+}
+
+export function listShareLinks(): ShareLink[] {
+  const rows = loadCollection('share_links')
+  return Object.values(rows).map((raw) => normalizeShareLink(raw as Record<string, unknown>))
+}
+
+export function loadShareLinkById(id: string): ShareLink | null {
+  const raw = loadStoredItem('share_links', id)
+  return raw ? normalizeShareLink(raw as Record<string, unknown>) : null
+}
+
+export function loadShareLinkByToken(token: string): ShareLink | null {
+  const trimmed = token.trim()
+  if (!trimmed) return null
+  for (const link of listShareLinks()) {
+    if (link.token === trimmed) return link
+  }
+  return null
+}
+
+export interface CreateShareLinkInput {
+  entityType: ShareEntityType
+  entityId: string
+  expiresInSec?: number | null
+  label?: string | null
+}
+
+export function createShareLink(input: CreateShareLinkInput): ShareLink {
+  const now = Date.now()
+  const link: ShareLink = {
+    id: genId(),
+    token: generateToken(),
+    entityType: input.entityType,
+    entityId: input.entityId,
+    label: input.label?.trim() || null,
+    createdAt: now,
+    expiresAt:
+      input.expiresInSec && input.expiresInSec > 0
+        ? now + input.expiresInSec * 1000
+        : null,
+    revokedAt: null,
+  }
+  upsertStoredItem('share_links', link.id, link)
+  return link
+}
+
+export function revokeShareLink(id: string): ShareLink | null {
+  const link = loadShareLinkById(id)
+  if (!link) return null
+  if (link.revokedAt) return link
+  const next: ShareLink = { ...link, revokedAt: Date.now() }
+  upsertStoredItem('share_links', next.id, next)
+  return next
+}
+
+export function deleteShareLink(id: string): void {
+  deleteStoredItem('share_links', id)
+}
+
+export function isShareLinkActive(link: ShareLink, now: number = Date.now()): boolean {
+  if (link.revokedAt) return false
+  if (link.expiresAt !== null && link.expiresAt <= now) return false
+  return true
+}
+
+function normalizeShareLink(raw: Record<string, unknown>): ShareLink {
+  const entityType = raw.entityType
+  const safeEntityType: ShareEntityType =
+    entityType === 'mission' || entityType === 'skill' || entityType === 'session' ? entityType : 'mission'
+  return {
+    id: typeof raw.id === 'string' ? raw.id : '',
+    token: typeof raw.token === 'string' ? raw.token : '',
+    entityType: safeEntityType,
+    entityId: typeof raw.entityId === 'string' ? raw.entityId : '',
+    label: typeof raw.label === 'string' ? raw.label : null,
+    createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : 0,
+    expiresAt: typeof raw.expiresAt === 'number' ? raw.expiresAt : null,
+    revokedAt: typeof raw.revokedAt === 'number' ? raw.revokedAt : null,
+  }
+}

package/src/lib/server/sharing/share-resolver.ts

@@ -0,0 +1,153 @@
+import type { ShareEntityType, ShareLink } from './share-link-repository'
+import { loadStoredItem } from '@/lib/server/storage'
+import { listMissionReports } from '@/lib/server/missions/mission-repository'
+
+export interface SharedMissionPayload {
+  kind: 'mission'
+  id: string
+  title: string
+  goal: string
+  successCriteria: string[]
+  status: string
+  createdAt: number
+  milestones: Array<{ at: number; note: string; kind: string }>
+  reports: Array<{ at: number; format: string; content: string }>
+}
+
+export interface SharedSkillPayload {
+  kind: 'skill'
+  id: string
+  name: string
+  description: string
+  tags: string[]
+  content: string
+  sourceFormat: string | null
+  createdAt: number | null
+}
+
+export interface SharedSessionPayload {
+  kind: 'session'
+  id: string
+  name: string
+  agentName: string | null
+  messages: Array<{ role: string; text: string; at: number | null }>
+  createdAt: number
+}
+
+export type SharedPayload = SharedMissionPayload | SharedSkillPayload | SharedSessionPayload
+
+const MAX_MESSAGES = 60
+const MAX_MILESTONES = 40
+const MAX_REPORTS = 10
+
+export function resolveSharedEntity(link: ShareLink): SharedPayload | null {
+  switch (link.entityType) {
+    case 'mission':
+      return resolveMission(link.entityId)
+    case 'skill':
+      return resolveSkill(link.entityId)
+    case 'session':
+      return resolveSession(link.entityId)
+    default:
+      return null
+  }
+}
+
+function resolveMission(id: string): SharedMissionPayload | null {
+  const raw = loadStoredItem('agent_missions', id) as Record<string, unknown> | null
+  if (!raw) return null
+  const milestonesRaw = Array.isArray(raw.milestones) ? raw.milestones : []
+  const milestones = milestonesRaw
+    .slice(-MAX_MILESTONES)
+    .map((m) => {
+      const entry = (m || {}) as Record<string, unknown>
+      return {
+        at: typeof entry.at === 'number' ? entry.at : 0,
+        note: typeof entry.note === 'string' ? entry.note : '',
+        kind: typeof entry.kind === 'string' ? entry.kind : 'note',
+      }
+    })
+
+  let reports: SharedMissionPayload['reports'] = []
+  try {
+    const rows = listMissionReports(id, MAX_REPORTS)
+    reports = rows.map((r) => ({
+      at: r.generatedAt,
+      format: String(r.format),
+      content: r.body,
+    }))
+  } catch {
+    reports = []
+  }
+
+  return {
+    kind: 'mission',
+    id,
+    title: typeof raw.title === 'string' ? raw.title : 'Untitled Mission',
+    goal: typeof raw.goal === 'string' ? raw.goal : '',
+    successCriteria: Array.isArray(raw.successCriteria)
+      ? (raw.successCriteria as unknown[]).filter((x): x is string => typeof x === 'string')
+      : [],
+    status: typeof raw.status === 'string' ? raw.status : 'unknown',
+    createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : 0,
+    milestones,
+    reports,
+  }
+}
+
+function resolveSkill(id: string): SharedSkillPayload | null {
+  const raw = loadStoredItem('skills', id) as Record<string, unknown> | null
+  if (!raw) return null
+  return {
+    kind: 'skill',
+    id,
+    name: typeof raw.name === 'string' ? raw.name : 'Unnamed Skill',
+    description: typeof raw.description === 'string' ? raw.description : '',
+    tags: Array.isArray(raw.tags)
+      ? (raw.tags as unknown[]).filter((x): x is string => typeof x === 'string')
+      : [],
+    content: typeof raw.content === 'string' ? raw.content : '',
+    sourceFormat: typeof raw.sourceFormat === 'string' ? raw.sourceFormat : null,
+    createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : null,
+  }
+}
+
+function resolveSession(id: string): SharedSessionPayload | null {
+  const raw = loadStoredItem('sessions', id) as Record<string, unknown> | null
+  if (!raw) return null
+  const messagesRaw = Array.isArray(raw.messages) ? raw.messages : []
+  const messages = messagesRaw.slice(-MAX_MESSAGES).map((m) => {
+    const entry = (m || {}) as Record<string, unknown>
+    return {
+      role: typeof entry.role === 'string' ? entry.role : 'unknown',
+      text: typeof entry.content === 'string' ? entry.content : '',
+      at: typeof entry.at === 'number' ? entry.at : null,
+    }
+  })
+
+  let agentName: string | null = null
+  const agentId = typeof raw.agentId === 'string' ? raw.agentId : null
+  if (agentId) {
+    const agent = loadStoredItem('agents', agentId) as Record<string, unknown> | null
+    if (agent && typeof agent.name === 'string') agentName = agent.name
+  }
+
+  return {
+    kind: 'session',
+    id,
+    name: typeof raw.name === 'string' ? raw.name : 'Untitled Session',
+    agentName,
+    messages,
+    createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : 0,
+  }
+}
+
+/**
+ * Shape enforced on every outbound shared payload: fields that should never
+ * leak off-instance. Reasons kept on the function to keep the allowlist obvious.
+ */
+export const SHARE_ALLOWED_ENTITY_TYPES: readonly ShareEntityType[] = [
+  'mission',
+  'skill',
+  'session',
+] as const

package/src/lib/server/storage.ts

@@ -182,6 +182,7 @@ const COLLECTIONS = [
   'agent_missions',
   'mission_reports',
   'agent_mission_events',
+  'share_links',
 ] as const
 
 export type StorageCollection = (typeof COLLECTIONS)[number]