oysterun 1.5.2 → 1.5.3-beta.0

package/dev/client/web/index.html

@@ -1145,6 +1145,48 @@
         justify-content: center;
       }
 
+      .agent-store-demo-backdrop {
+        z-index: 10020;
+      }
+
+      .agent-store-demo-status {
+        min-height: 42px;
+        margin-top: 14px;
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        color: var(--ink-soft);
+        font-size: 14px;
+        line-height: 1.45;
+      }
+
+      .agent-store-demo-spinner {
+        width: 16px;
+        height: 16px;
+        flex: 0 0 16px;
+        border: 2px solid rgba(151, 89, 49, 0.22);
+        border-top-color: var(--accent);
+        border-radius: 50%;
+        animation: oysterun-auth-spin 800ms linear infinite;
+      }
+
+      .browse-create-folder-modal .agent-store-demo-actions {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr);
+        gap: 10px;
+      }
+
+      .agent-store-demo-actions > button {
+        min-width: 0;
+        justify-content: center;
+      }
+
+      #agent-store-demo-submit-btn {
+        display: inline-flex;
+        align-items: center;
+        gap: 9px;
+      }
+
       #app {
         display: none;
         height: 100vh;
@@ -7846,6 +7888,26 @@
                 >
               </div>
               <div class="topbar-right">
+                <button
+                  class="sessions-compose-button topbar-agent-store hidden"
+                  id="entry-agent-store-btn"
+                  type="button"
+                  aria-label="Agent Store"
+                  title="Agent Store"
+                  data-testid="oysterun-agent-store-demo"
+                  onClick=${call("openAgentStoreDemo")}
+                >
+                  <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                    <path
+                      d="M4 9.25h16v10.5H4V9.25Zm2-5h12l2 5H4l2-5Zm4 5v10.5m4-10.5v10.5"
+                      fill="none"
+                      stroke="currentColor"
+                      stroke-width="1.7"
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                    ></path>
+                  </svg>
+                </button>
                 <button
                   class="sessions-compose-button topbar-sessions-compose hidden"
                   id="entry-start-session-btn"
@@ -11040,6 +11102,126 @@ Terminal output will appear here.</pre
           `;
         }
 
+        function AgentStoreDemoModal() {
+          return html`
+            <div
+              id="agent-store-demo-backdrop"
+              class="modal-backdrop sheet browse-create-folder-backdrop agent-store-demo-backdrop hidden"
+              onClick=${closeBackdrop("closeAgentStoreDemo")}
+            >
+              <div
+                class="modal sheet narrow browse-create-folder-modal agent-store-demo-modal"
+                role="dialog"
+                aria-modal="true"
+                aria-labelledby="agent-store-demo-title"
+                data-oysterun-agent-store-demo="true"
+              >
+                <button
+                  class="modal-close-btn browse-create-folder-close-btn"
+                  id="agent-store-demo-close-btn"
+                  type="button"
+                  aria-label="Close"
+                  title="Close"
+                  onClick=${call("closeAgentStoreDemo")}
+                >
+                  x
+                </button>
+                <div class="modal-scroll">
+                  <span class="eyebrow">Agent Store Demo</span>
+                  <h2 id="agent-store-demo-title">Clone GitHub Agent</h2>
+                  <div class="field" style="margin-top:14px">
+                    <label for="agent-store-demo-repository-select"
+                      >Demo Repository</label
+                    >
+                    <select
+                      id="agent-store-demo-repository-select"
+                      onChange=${(event) =>
+                        window.handleAgentStoreDemoRepositorySelect?.(event)}
+                    >
+                      <option value="">Choose a demo repository</option>
+                      <option
+                        value="https://github.com/GoatWang/oysterun-ccstock-workenv"
+                      >
+                        CCStock WorkEnv
+                      </option>
+                      <option
+                        value="https://github.com/GoatWang/oysterun-ccstock-workenv-en"
+                      >
+                        CCStock WorkEnv (English)
+                      </option>
+                      <option
+                        value="https://github.com/GoatWang/oysterun-github-tracker"
+                      >
+                        GitHub Tracker
+                      </option>
+                    </select>
+                  </div>
+                  <div class="field" style="margin-top:14px">
+                    <label for="agent-store-demo-url-input"
+                      >GitHub Repository URL</label
+                    >
+                    <input
+                      id="agent-store-demo-url-input"
+                      type="url"
+                      inputmode="url"
+                      autocomplete="url"
+                      autocapitalize="none"
+                      spellcheck="false"
+                      placeholder="https://github.com/owner/repository"
+                      onInput=${(event) =>
+                        window.handleAgentStoreDemoUrlInput?.(event)}
+                      onKeyDown=${(event) =>
+                        window.handleAgentStoreDemoUrlKeyDown?.(event)}
+                    />
+                  </div>
+                  <div
+                    id="agent-store-demo-status"
+                    class="agent-store-demo-status hidden"
+                    role="status"
+                    aria-live="polite"
+                    aria-atomic="true"
+                  >
+                    <span
+                      id="agent-store-demo-status-spinner"
+                      class="agent-store-demo-spinner"
+                      aria-hidden="true"
+                    ></span>
+                    <span id="agent-store-demo-status-text"></span>
+                  </div>
+                  <div
+                    id="agent-store-demo-error"
+                    class="error-box hidden"
+                    style="margin-top:12px"
+                  ></div>
+                </div>
+                <div class="modal-actions agent-store-demo-actions">
+                  <button
+                    class="btn-primary"
+                    id="agent-store-demo-submit-btn"
+                    type="button"
+                    onClick=${call("submitAgentStoreDemo")}
+                  >
+                    <span
+                      id="agent-store-demo-submit-spinner"
+                      class="agent-store-demo-spinner hidden"
+                      aria-hidden="true"
+                    ></span>
+                    <span id="agent-store-demo-submit-label">OK</span>
+                  </button>
+                  <button
+                    class="btn-secondary hidden"
+                    id="agent-store-demo-session-setup-btn"
+                    type="button"
+                    onClick=${call("openAgentStoreDemoSessionSetup")}
+                  >
+                    Open Session Setup
+                  </button>
+                </div>
+              </div>
+            </div>
+          `;
+        }
+
         function ProviderAuthModal() {
           return html`
             <div
@@ -11380,6 +11562,7 @@ Waiting for Claude login output…</pre
             <div id="browse-context-menu" class="browse-context-menu hidden" role="menu" aria-hidden="true" tabindex="-1"></div>
             <div id="app-toast" class="app-toast hidden" role="status" aria-live="polite" aria-atomic="true"></div>
             <${BrowseCreateFolderModal} />
+            <${AgentStoreDemoModal} />
             <${ProviderAuthModal} />
             <${ChatImagePreviewModal} />
             <${HiddenCache} />
@@ -13211,6 +13394,18 @@ Waiting for Claude login output…</pre
           error: "",
         };
       }
+
+      function createAgentStoreDemoState() {
+        return {
+          visible: false,
+          phase: "idle",
+          repositoryUrl: "",
+          status: "",
+          error: "",
+          clone: null,
+          requestId: 0,
+        };
+      }
       function createTerminalViewState() {
         return {
           terminal: null,
@@ -13386,6 +13581,7 @@ Waiting for Claude login output…</pre
         updatedAt: 0,
       };
       let providerAuthModalState = createProviderAuthModalState();
+      let agentStoreDemoState = createAgentStoreDemoState();
       let chatImagePreviewState = {
         visible: false,
         requestKey: "",
@@ -18218,6 +18414,376 @@ Waiting for Claude login output…</pre
       window.openExplorerFromSessionsEmptyState =
         openExplorerFromSessionsEmptyState;
 
+      const AGENT_STORE_DEMO_PENDING_PHASES = new Set([
+        "validating",
+        "cloning",
+        "loading_config",
+        "starting_session",
+      ]);
+
+      const AGENT_STORE_DEMO_REPOSITORY_URLS = new Set([
+        "https://github.com/GoatWang/oysterun-ccstock-workenv",
+        "https://github.com/GoatWang/oysterun-ccstock-workenv-en",
+        "https://github.com/GoatWang/oysterun-github-tracker",
+      ]);
+
+      function isAgentStoreDemoPending() {
+        return AGENT_STORE_DEMO_PENDING_PHASES.has(agentStoreDemoState.phase);
+      }
+
+      function getAgentStoreDemoPendingLabel() {
+        if (agentStoreDemoState.phase === "validating") return "Validating...";
+        if (agentStoreDemoState.phase === "cloning") return "Cloning...";
+        if (agentStoreDemoState.phase === "loading_config")
+          return "Loading config...";
+        if (agentStoreDemoState.phase === "starting_session")
+          return "Starting session...";
+        return "OK";
+      }
+
+      function renderAgentStoreDemo() {
+        const backdrop = $("agent-store-demo-backdrop");
+        if (!backdrop) return;
+        const pending = isAgentStoreDemoPending();
+        const cloneComplete = Boolean(agentStoreDemoState.clone?.agent_folder);
+        const input = $("agent-store-demo-url-input");
+        const repositorySelect = $("agent-store-demo-repository-select");
+        const closeButton = $("agent-store-demo-close-btn");
+        const submitButton = $("agent-store-demo-submit-btn");
+        const submitLabel = $("agent-store-demo-submit-label");
+
+        backdrop.classList.toggle(
+          "hidden",
+          agentStoreDemoState.visible !== true
+        );
+        backdrop.dataset.phase = agentStoreDemoState.phase;
+        if (input) {
+          if (input.value !== agentStoreDemoState.repositoryUrl) {
+            input.value = agentStoreDemoState.repositoryUrl;
+          }
+          input.disabled = pending || cloneComplete;
+        }
+        if (repositorySelect) {
+          repositorySelect.value = AGENT_STORE_DEMO_REPOSITORY_URLS.has(
+            agentStoreDemoState.repositoryUrl
+          )
+            ? agentStoreDemoState.repositoryUrl
+            : "";
+          repositorySelect.disabled = pending || cloneComplete;
+        }
+        if (closeButton) closeButton.disabled = pending;
+        if (submitButton) {
+          submitButton.disabled =
+            pending ||
+            cloneComplete ||
+            !agentStoreDemoState.repositoryUrl.trim();
+          submitButton.classList.toggle(
+            "hidden",
+            agentStoreDemoState.phase === "failed_after_clone"
+          );
+        }
+        if (submitLabel)
+          submitLabel.textContent = getAgentStoreDemoPendingLabel();
+        setVisible("agent-store-demo-submit-spinner", pending);
+        setVisible("agent-store-demo-status", pending);
+        setText(
+          "agent-store-demo-status-text",
+          agentStoreDemoState.status || ""
+        );
+        showError("agent-store-demo-error", agentStoreDemoState.error || "");
+        setVisible(
+          "agent-store-demo-session-setup-btn",
+          agentStoreDemoState.phase === "failed_after_clone" && cloneComplete
+        );
+      }
+
+      function openAgentStoreDemo() {
+        if (isAgentStoreDemoPending()) return;
+        agentStoreDemoState = {
+          ...createAgentStoreDemoState(),
+          visible: true,
+          requestId: agentStoreDemoState.requestId + 1,
+        };
+        renderAgentStoreDemo();
+        requestAnimationFrame(() => {
+          $("agent-store-demo-url-input")?.focus({ preventScroll: true });
+        });
+      }
+
+      function closeAgentStoreDemo(opts = {}) {
+        if (isAgentStoreDemoPending() && opts.force !== true) return;
+        agentStoreDemoState = {
+          ...createAgentStoreDemoState(),
+          requestId: agentStoreDemoState.requestId + 1,
+        };
+        renderAgentStoreDemo();
+      }
+
+      function handleAgentStoreDemoUrlInput(event) {
+        if (isAgentStoreDemoPending() || agentStoreDemoState.clone) return;
+        agentStoreDemoState = {
+          ...agentStoreDemoState,
+          phase: "idle",
+          repositoryUrl: event?.target?.value || "",
+          status: "",
+          error: "",
+        };
+        renderAgentStoreDemo();
+      }
+
+      function handleAgentStoreDemoRepositorySelect(event) {
+        if (isAgentStoreDemoPending() || agentStoreDemoState.clone) return;
+        const repositoryUrl = String(event?.target?.value || "").trim();
+        if (!repositoryUrl) return;
+        agentStoreDemoState = {
+          ...agentStoreDemoState,
+          phase: "idle",
+          repositoryUrl,
+          status: "",
+          error: "",
+        };
+        renderAgentStoreDemo();
+        requestAnimationFrame(() => {
+          $("agent-store-demo-url-input")?.focus({ preventScroll: true });
+        });
+      }
+
+      function handleAgentStoreDemoUrlKeyDown(event) {
+        if (event?.key !== "Enter" || event.isComposing) return;
+        event.preventDefault();
+        if (!isAgentStoreDemoPending()) void submitAgentStoreDemo();
+      }
+
+      function validateAgentStoreDemoUrl(value) {
+        let parsed;
+        try {
+          parsed = new URL(String(value || "").trim());
+        } catch {
+          throw new Error("Enter a valid public GitHub HTTPS repository URL.");
+        }
+        if (
+          parsed.protocol !== "https:" ||
+          parsed.hostname.toLowerCase() !== "github.com" ||
+          parsed.username ||
+          parsed.password ||
+          parsed.port ||
+          parsed.search ||
+          parsed.hash ||
+          !/^\/[^/]+\/[^/]+\/?$/.test(parsed.pathname)
+        ) {
+          throw new Error(
+            "Only public https://github.com/<owner>/<repo> URLs are supported."
+          );
+        }
+        return parsed.toString();
+      }
+
+      async function getAgentStoreDemoProviderSkillInstallDecision({
+        agentId,
+        agentFolder,
+        provider,
+      }) {
+        const params = new URLSearchParams({
+          agent_id: agentId,
+          agent_folder: agentFolder,
+          provider,
+        });
+        try {
+          const status = await apiWithAuthRetry(
+            "GET",
+            `/agent/provider-skill-status?${params.toString()}`
+          );
+          return (
+            status?.default_checked === true &&
+            status?.can_install === true &&
+            status?.disabled !== true
+          );
+        } catch {
+          return false;
+        }
+      }
+
+      function buildAgentStoreDemoSessionStartPayload({
+        clone,
+        folderConfig,
+        installOysterunSkills,
+      }) {
+        const provider = String(folderConfig?.provider || "").trim();
+        const model = String(folderConfig?.model || "").trim();
+        if (!provider || !model) {
+          throw new Error(
+            "The cloned folder did not resolve a provider and model."
+          );
+        }
+        const payload = {
+          agent_id: clone.agent_id,
+          agent_folder: clone.agent_folder,
+          provider,
+          model,
+          interface_type: normalizeFirstPartyInterfaceType(
+            folderConfig.interfaceType || "coding"
+          ),
+          reasoning_effort: folderConfig.reasoningEffort || undefined,
+          dangerous_mode: folderConfig.dangerousMode === true,
+          allow_dangerously_skip_permissions:
+            folderConfig.allowDangerouslySkipPermissions === true,
+          install_oysterun_skills: installOysterunSkills === true,
+        };
+        if (provider === "claude") {
+          payload.permission_mode = folderConfig.permissionMode;
+        } else if (provider === "codex") {
+          payload.approval_policy = folderConfig.approvalPolicy;
+        }
+        const proof = {
+          ...buildCreateSessionSetupProviderModelPermissionProof(payload),
+          proof_surface: "visible_agent_store_clone_modal_state",
+        };
+        payload.session_setup_provider_model_permission_proof = proof;
+        return { payload, proof };
+      }
+
+      function finalizeAgentStoreDemoStartedSession(data, expectedProof) {
+        const proofValidation =
+          validateSessionSetupProviderModelPermissionProofResponse(
+            data,
+            expectedProof,
+            { requireCountableStartResponseProof: true }
+          );
+        if (!proofValidation.ok) {
+          throw new Error(
+            `Session Setup proof validation failed: ${proofValidation.errors.join(
+              " "
+            )}`
+          );
+        }
+        const normalizedData = {
+          ...data,
+          session_setup_provider_model_permission_proof: proofValidation.proof,
+        };
+        clearPendingAttachments();
+        primeSelectedAgentFromStart(normalizedData);
+        const startedLiveSession =
+          upsertStartedSessionIntoLiveCatalog(normalizedData);
+        invalidateDashboardDataCaches({
+          catalog: true,
+          sessions: true,
+          history: true,
+          transcripts: true,
+        });
+        if (
+          !startedLiveSession ||
+          startedLiveSession.sessionId !== normalizedData.session_id
+        ) {
+          throw new Error(
+            "Agent Store could not materialize the started Host session before opening chat."
+          );
+        }
+        return normalizedData.session_id;
+      }
+
+      async function submitAgentStoreDemo() {
+        if (isAgentStoreDemoPending() || agentStoreDemoState.clone) return;
+        const requestId = agentStoreDemoState.requestId + 1;
+        agentStoreDemoState = {
+          ...agentStoreDemoState,
+          phase: "validating",
+          status: "Validating GitHub repository...",
+          error: "",
+          requestId,
+        };
+        renderAgentStoreDemo();
+
+        try {
+          const repositoryUrl = validateAgentStoreDemoUrl(
+            agentStoreDemoState.repositoryUrl
+          );
+          agentStoreDemoState = {
+            ...agentStoreDemoState,
+            phase: "cloning",
+            status: "Cloning the repository into Default Browse Root...",
+          };
+          renderAgentStoreDemo();
+          const clone = await apiWithAuthRetry(
+            "POST",
+            "/agent-store/demo/clone",
+            { repository_url: repositoryUrl }
+          );
+          if (agentStoreDemoState.requestId !== requestId) return;
+
+          agentStoreDemoState = {
+            ...agentStoreDemoState,
+            phase: "loading_config",
+            status: "Loading the cloned agent configuration...",
+            clone,
+          };
+          renderAgentStoreDemo();
+          const folderConfig = await apiWithAuthRetry(
+            "GET",
+            `/dev/folder-config?path=${encodeURIComponent(clone.agent_folder)}`
+          );
+          if (agentStoreDemoState.requestId !== requestId) return;
+          const installOysterunSkills =
+            await getAgentStoreDemoProviderSkillInstallDecision({
+              agentId: clone.agent_id,
+              agentFolder: clone.agent_folder,
+              provider: folderConfig.provider,
+            });
+          const { payload, proof } = buildAgentStoreDemoSessionStartPayload({
+            clone,
+            folderConfig,
+            installOysterunSkills,
+          });
+
+          agentStoreDemoState = {
+            ...agentStoreDemoState,
+            phase: "starting_session",
+            status: "Starting a session with the resolved agent settings...",
+          };
+          renderAgentStoreDemo();
+          const data = await apiWithAuthRetry(
+            "POST",
+            "/session/start",
+            payload
+          );
+          if (agentStoreDemoState.requestId !== requestId) return;
+          const sessionId = finalizeAgentStoreDemoStartedSession(data, proof);
+          closeAgentStoreDemo({ force: true });
+          openRouteCForStartedSession(sessionId);
+        } catch (err) {
+          if (agentStoreDemoState.requestId !== requestId) return;
+          const cloneComplete = Boolean(
+            agentStoreDemoState.clone?.agent_folder
+          );
+          const detail = String(err?.data?.detail || "").trim();
+          const message = cloneComplete
+            ? formatCreateStepError("Could not start session", err)
+            : err?.message || "Could not clone the GitHub repository.";
+          agentStoreDemoState = {
+            ...agentStoreDemoState,
+            phase: cloneComplete ? "failed_after_clone" : "failed_before_clone",
+            status: "",
+            error: detail ? `${message}\n${detail}` : message,
+          };
+          renderAgentStoreDemo();
+        }
+      }
+
+      function openAgentStoreDemoSessionSetup() {
+        const folder = agentStoreDemoState.clone?.agent_folder || "";
+        if (!folder || isAgentStoreDemoPending()) return;
+        closeAgentStoreDemo({ force: true });
+        openCreateModal(folder);
+      }
+
+      window.openAgentStoreDemo = openAgentStoreDemo;
+      window.closeAgentStoreDemo = closeAgentStoreDemo;
+      window.handleAgentStoreDemoUrlInput = handleAgentStoreDemoUrlInput;
+      window.handleAgentStoreDemoRepositorySelect =
+        handleAgentStoreDemoRepositorySelect;
+      window.handleAgentStoreDemoUrlKeyDown = handleAgentStoreDemoUrlKeyDown;
+      window.submitAgentStoreDemo = submitAgentStoreDemo;
+      window.openAgentStoreDemoSessionSetup = openAgentStoreDemoSessionSetup;
+
       function getHostDefaultRuntime() {
         return (
           hostPreferencesState.effectiveDefaultProvider ||
@@ -29060,6 +29626,7 @@ Waiting for Claude login output…</pre
         setVisible("browser-site-next-btn", isBrowser);
         setVisible("browser-site-share-btn", isBrowser);
         setVisible("browser-site-exit-btn", isBrowser);
+        setVisible("entry-agent-store-btn", screen === "sessions");
         setVisible("entry-start-session-btn", screen === "sessions");
         setVisible("topbar-scheduler-new-btn", isSchedulerList);
         setVisible("topbar-scheduler-refresh-btn", isSchedulerList);
@@ -29570,6 +30137,7 @@ Waiting for Claude login output…</pre
         "browse-context-menu",
         "picker-modal-backdrop",
         "browse-create-folder-backdrop",
+        "agent-store-demo-backdrop",
         "provider-auth-backdrop",
         "chat-image-preview-backdrop",
         "command-palette",

package/host-service/agent-store-demo.mjs

@@ -0,0 +1,369 @@
+import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+import { lstat, realpath, rename, rm, stat } from "fs/promises";
+import { join, relative } from "path";
+import { resolveDefaultBrowsePathAsync } from "./config.mjs";
+import { deriveBrowserRootProjectId } from "./browser-root-project-index.mjs";
+
+export const AGENT_STORE_DEMO_CLONE_TIMEOUT_MS = Math.max(
+  1,
+  Number.parseInt(
+    process.env.OYSTERUN_AGENT_STORE_DEMO_CLONE_TIMEOUT_MS || "120000",
+    10
+  ) || 120000
+);
+
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024;
+const GIT_KILL_GRACE_MS = 1500;
+const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const GITHUB_REPOSITORY_PATTERN = /^[A-Za-z0-9_.-]+$/;
+
+function createAgentStoreError(message, status, code, detail = "") {
+  const error = new Error(message);
+  error.status = status;
+  error.code = code;
+  if (detail) error.detail = detail;
+  return error;
+}
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function appendBoundedOutput(current, chunk) {
+  if (current.length >= MAX_GIT_OUTPUT_BYTES) return current;
+  return `${current}${String(chunk)}`.slice(0, MAX_GIT_OUTPUT_BYTES);
+}
+
+function summarizeGitError(stderr, stdout) {
+  const value = normalizeString(stderr) || normalizeString(stdout);
+  return value.slice(0, 2000);
+}
+
+async function pathExists(path) {
+  return Boolean(await lstat(path).catch(() => null));
+}
+
+function assertDirectChild(candidate, root) {
+  const relativePath = relative(root, candidate);
+  if (
+    !relativePath ||
+    relativePath.startsWith("..") ||
+    relativePath.startsWith("/") ||
+    relativePath.includes("/") ||
+    relativePath.includes("\\")
+  ) {
+    throw createAgentStoreError(
+      "Agent Store destination must be a direct child of Default Browse Root",
+      400,
+      "agent_store_destination_invalid"
+    );
+  }
+}
+
+export function parsePublicGitHubRepositoryUrl(rawValue) {
+  const raw = normalizeString(rawValue);
+  if (!raw) {
+    throw createAgentStoreError(
+      "GitHub Repository URL is required",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw createAgentStoreError(
+      "Enter a valid public GitHub HTTPS repository URL",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  if (!/^https:\/\/github\.com\//i.test(raw)) {
+    throw createAgentStoreError(
+      "Only public https://github.com/<owner>/<repo> URLs are supported",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.hostname.toLowerCase() !== "github.com" ||
+    parsed.username ||
+    parsed.password ||
+    parsed.port ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw createAgentStoreError(
+      "Only public https://github.com/<owner>/<repo> URLs are supported",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/?$/);
+  if (!match) {
+    throw createAgentStoreError(
+      "GitHub URL must contain exactly one owner and repository",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  let owner;
+  let repositorySegment;
+  try {
+    owner = decodeURIComponent(match[1]);
+    repositorySegment = decodeURIComponent(match[2]);
+  } catch {
+    throw createAgentStoreError(
+      "GitHub URL contains invalid path encoding",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+  const repositoryName = repositorySegment.endsWith(".git")
+    ? repositorySegment.slice(0, -4)
+    : repositorySegment;
+
+  if (
+    !GITHUB_OWNER_PATTERN.test(owner) ||
+    !GITHUB_REPOSITORY_PATTERN.test(repositoryName) ||
+    repositoryName === "." ||
+    repositoryName === ".."
+  ) {
+    throw createAgentStoreError(
+      "GitHub owner or repository name is invalid",
+      400,
+      "invalid_github_repository_url"
+    );
+  }
+
+  return {
+    owner,
+    repositoryName,
+    repositoryUrl: `https://github.com/${owner}/${repositoryName}`,
+    cloneUrl: `https://github.com/${owner}/${repositoryName}.git`,
+    agentId: deriveBrowserRootProjectId(repositoryName),
+  };
+}
+
+function terminateGitProcess(child, signal) {
+  if (!child) return;
+  if (process.platform !== "win32" && Number.isInteger(child.pid)) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+      // Fall through to the direct child when the process group is unavailable.
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // The process may already have exited.
+  }
+}
+
+export function runGitShallowClone({
+  cloneUrl,
+  destinationPath,
+  timeoutMs = AGENT_STORE_DEMO_CLONE_TIMEOUT_MS,
+  spawnImpl = spawn,
+} = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let child;
+    try {
+      child = spawnImpl(
+        "git",
+        ["clone", "--depth", "1", "--", cloneUrl, destinationPath],
+        {
+          detached: process.platform !== "win32",
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"],
+        }
+      );
+    } catch (err) {
+      rejectPromise(
+        createAgentStoreError(
+          err?.code === "ENOENT"
+            ? "Git is not available on this Host"
+            : "Could not start Git clone",
+          err?.code === "ENOENT" ? 503 : 502,
+          err?.code === "ENOENT" ? "git_unavailable" : "agent_store_clone_failed"
+        )
+      );
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let forceKillTimer = null;
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      terminateGitProcess(child, "SIGTERM");
+      forceKillTimer = setTimeout(() => {
+        terminateGitProcess(child, "SIGKILL");
+      }, GIT_KILL_GRACE_MS);
+    }, timeoutMs);
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+    };
+
+    const rejectOnce = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      rejectPromise(error);
+    };
+
+    child.stdout?.on("data", (chunk) => {
+      stdout = appendBoundedOutput(stdout, chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = appendBoundedOutput(stderr, chunk);
+    });
+    child.once("error", (err) => {
+      rejectOnce(
+        createAgentStoreError(
+          err?.code === "ENOENT"
+            ? "Git is not available on this Host"
+            : "Could not start Git clone",
+          err?.code === "ENOENT" ? 503 : 502,
+          err?.code === "ENOENT" ? "git_unavailable" : "agent_store_clone_failed"
+        )
+      );
+    });
+    child.once("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (timedOut) {
+        rejectPromise(
+          createAgentStoreError(
+            "GitHub clone timed out",
+            504,
+            "agent_store_clone_timeout"
+          )
+        );
+        return;
+      }
+      if (code !== 0) {
+        rejectPromise(
+          createAgentStoreError(
+            "Could not clone the GitHub repository",
+            502,
+            "agent_store_clone_failed",
+            summarizeGitError(stderr, stdout) ||
+              `git exited with code ${code ?? "unknown"}${
+                signal ? ` (${signal})` : ""
+              }`
+          )
+        );
+        return;
+      }
+      resolvePromise({ stdout, stderr, exitCode: code });
+    });
+  });
+}
+
+export async function clonePublicGitHubAgent({
+  repositoryUrl,
+  browseRoot = null,
+  timeoutMs = AGENT_STORE_DEMO_CLONE_TIMEOUT_MS,
+  runClone = runGitShallowClone,
+  requestId = randomUUID(),
+} = {}) {
+  const repository = parsePublicGitHubRepositoryUrl(repositoryUrl);
+  const requestedRoot = browseRoot || (await resolveDefaultBrowsePathAsync());
+  const rootPath = await realpath(requestedRoot);
+  const rootStats = await stat(rootPath);
+  if (!rootStats.isDirectory()) {
+    throw createAgentStoreError(
+      "Default Browse Root is not a directory",
+      400,
+      "agent_store_browse_root_invalid"
+    );
+  }
+
+  const finalPath = join(rootPath, repository.repositoryName);
+  assertDirectChild(finalPath, rootPath);
+  if (await pathExists(finalPath)) {
+    throw createAgentStoreError(
+      "Agent folder already exists",
+      409,
+      "agent_folder_already_exists"
+    );
+  }
+
+  const stagingName = `.oysterun-agent-store-${repository.agentId}-${requestId}.partial`;
+  const stagingPath = join(rootPath, stagingName);
+  assertDirectChild(stagingPath, rootPath);
+  if (await pathExists(stagingPath)) {
+    throw createAgentStoreError(
+      "Agent Store staging folder already exists",
+      409,
+      "agent_store_staging_conflict"
+    );
+  }
+
+  let finalized = false;
+  try {
+    await runClone({
+      cloneUrl: repository.cloneUrl,
+      destinationPath: stagingPath,
+      timeoutMs,
+    });
+    const stagingStats = await stat(stagingPath).catch(() => null);
+    if (!stagingStats?.isDirectory()) {
+      throw createAgentStoreError(
+        "Git clone did not create an agent folder",
+        502,
+        "agent_store_clone_failed"
+      );
+    }
+    if (await pathExists(finalPath)) {
+      throw createAgentStoreError(
+        "Agent folder already exists",
+        409,
+        "agent_store_clone_finalize_conflict"
+      );
+    }
+    try {
+      await rename(stagingPath, finalPath);
+    } catch (err) {
+      if (["EEXIST", "ENOTEMPTY"].includes(err?.code)) {
+        throw createAgentStoreError(
+          "Agent folder already exists",
+          409,
+          "agent_store_clone_finalize_conflict"
+        );
+      }
+      throw err;
+    }
+    finalized = true;
+    return {
+      status: "agent_store_demo_clone_complete",
+      repository_url: repository.repositoryUrl,
+      repository_owner: repository.owner,
+      repository_name: repository.repositoryName,
+      agent_id: repository.agentId,
+      agent_folder: await realpath(finalPath),
+      clone_depth: 1,
+    };
+  } finally {
+    if (!finalized) {
+      await rm(stagingPath, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}

package/host-service/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oysterun-host-service",
-  "version": "1.5.2",
+  "version": "1.5.3-beta.0",
   "type": "module",
   "description": "Oysterun host service — runs on Mac mini, manages Claude Code sessions",
   "scripts": {

package/host-service/server.mjs

@@ -117,6 +117,7 @@ import {
   listFolderPage,
   validateFolderPath,
 } from "./folder-browser.mjs";
+import { clonePublicGitHubAgent } from "./agent-store-demo.mjs";
 import { attachRuntimeTurnId } from "./runtime-turn-events.mjs";
 import { TerminalSessionManager } from "./terminal-session-manager.mjs";
 import {
@@ -13454,6 +13455,44 @@ const server = createServer(async (req, res) => {
       }
     }
 
+    if (req.method === "POST" && path === "/agent-store/demo/clone") {
+      if (!requireDashboardMode(claims, res)) return;
+      try {
+        const body = await readBody(req);
+        const payload = await clonePublicGitHubAgent({
+          repositoryUrl: body.repository_url,
+        });
+        const snapshot = browserRootProjectIndex.refresh({
+          reason: "agent_store_demo_clone",
+          rebuildWatchers: true,
+        });
+        const discoveredProject = snapshot.projects.find(
+          (project) => project.agent_folder === payload.agent_folder
+        );
+        return respond(res, 201, {
+          ...payload,
+          project_discovery: discoveredProject
+            ? {
+                status: "browser_root_project_discovered",
+                project_id: discoveredProject.project_id,
+                agent_folder: discoveredProject.agent_folder,
+              }
+            : {
+                status: "browser_root_folder_unmarked",
+                project_id: payload.agent_id,
+                agent_folder: payload.agent_folder,
+              },
+        });
+      } catch (err) {
+        const response = {
+          error: err.message || "Could not clone the GitHub repository",
+          code: err.code || "agent_store_clone_failed",
+        };
+        if (err.detail) response.detail = err.detail;
+        return respond(res, err.status || 500, response);
+      }
+    }
+
     if (req.method === "POST" && path === "/dev/open-permissions-settings") {
       if (!requireDashboardMode(claims, res)) return;
       if (!supportsMacFolderAccessPermissions()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oysterun",
-  "version": "1.5.2",
+  "version": "1.5.3-beta.0",
   "type": "module",
   "description": "Oysterun Host installer and local service",
   "bin": {