@agent-native/core 0.155.0 → 0.157.1

package/corpus/templates/clips/server/lib/s3-upload-provider.ts

@@ -784,13 +784,40 @@ export const s3FileUploadProvider: FileUploadProvider = {
           )
           .join("") +
         "</CompleteMultipartUpload>";
-      const res = await signedS3Request(cfg, meta.objectKey, {
-        method: "POST",
-        query: { uploadId: session.sessionId },
-        body: new TextEncoder().encode(manifest),
-        contentType: "application/xml",
-        timeoutMs: S3_PUT_TIMEOUT_MS,
-      });
+      let res: Response;
+      try {
+        res = await signedS3Request(cfg, meta.objectKey, {
+          method: "POST",
+          query: { uploadId: session.sessionId },
+          body: new TextEncoder().encode(manifest),
+          contentType: "application/xml",
+          timeoutMs: S3_PUT_TIMEOUT_MS,
+        });
+      } catch (error) {
+        // R2 can finish the object while the HTTP response is lost. Reconcile
+        // that ambiguous case before the caller aborts the provider session.
+        try {
+          if (await verifyCompletedMultipartObject(cfg, meta)) {
+            await deleteObject(cfg, meta.stagingKey).catch((cleanupError) => {
+              console.warn(
+                "[s3-upload] failed to delete multipart staging object:",
+                cleanupError instanceof Error
+                  ? cleanupError.message
+                  : String(cleanupError),
+              );
+            });
+            return publicObjectUrl(cfg, meta.objectKey);
+          }
+        } catch (verificationError) {
+          console.warn(
+            "[s3-upload] completion reconciliation failed:",
+            verificationError,
+          );
+        }
+        throw new Error(
+          `S3 CompleteMultipartUpload failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
       const body = await res.text().catch(() => "");
       if (!res.ok || /<Error(?:\s|>)/.test(body)) {
         // CompleteMultipartUpload is not idempotent at the S3 API level. If

package/corpus/templates/clips/server/lib/upload-interruption.ts

@@ -1,8 +1,22 @@
 export const RETRYABLE_UPLOAD_INTERRUPTION_REASON =
   "Upload was interrupted. The local recording is safe; retry from the Clips desktop app.";
 
+export function retryableUploadInterruptionReason(
+  detail: string | null | undefined,
+): string {
+  const normalized = detail?.trim();
+  return normalized
+    ? `${RETRYABLE_UPLOAD_INTERRUPTION_REASON} Last error: ${normalized}`
+    : RETRYABLE_UPLOAD_INTERRUPTION_REASON;
+}
+
 export function isRetryableUploadInterruption(
   failureReason: string | null | undefined,
 ): boolean {
-  return failureReason === RETRYABLE_UPLOAD_INTERRUPTION_REASON;
+  return (
+    failureReason === RETRYABLE_UPLOAD_INTERRUPTION_REASON ||
+    failureReason?.startsWith(
+      `${RETRYABLE_UPLOAD_INTERRUPTION_REASON} Last error:`,
+    ) === true
+  );
 }

package/corpus/templates/clips/server/lib/upload-lease.ts

@@ -15,6 +15,8 @@ import { getDbExec, isPostgres } from "@agent-native/core/db";
 import { and, eq, inArray, isNull, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
+import type { StoredResumableSession } from "./resumable-session.js";
+import { abortResumableUploadSession } from "./resumable-upload-cleanup.js";
 
 /**
  * ponytail: one horizon for both in-progress statuses. A paused recorder emits
@@ -148,6 +150,61 @@ export interface ReapResult {
   expired: ReapedUpload[];
   failed: number;
   scratchKeysDeleted: number;
+  resumableSessionsAborted: number;
+  resumableCleanupFailed: number;
+}
+
+function resumableSessionKey(
+  recordingId: string,
+  generationId: string | null,
+): string {
+  return generationId
+    ? `resumable-session-${recordingId}-${generationId}`
+    : `resumable-session-${recordingId}`;
+}
+
+function parseStoredResumableSession(
+  value: unknown,
+): StoredResumableSession | null {
+  let parsed: unknown = value;
+  if (typeof parsed === "string") {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      // coercion-ok: malformed persisted session is absent, not an active session.
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const candidate = parsed as Record<string, unknown>;
+  if (
+    typeof candidate.providerId !== "string" ||
+    typeof candidate.sessionId !== "string" ||
+    !candidate.meta ||
+    typeof candidate.meta !== "object" ||
+    typeof candidate.bytesUploaded !== "number" ||
+    !Number.isFinite(candidate.bytesUploaded) ||
+    candidate.bytesUploaded < 0
+  ) {
+    return null;
+  }
+  return candidate as unknown as StoredResumableSession;
+}
+
+async function readResumableSessionState(
+  exec: ReturnType<typeof getDbExec>,
+  placeholder: string,
+  key: string,
+): Promise<{ present: boolean; session: StoredResumableSession | null }> {
+  const result = await exec.execute({
+    sql: `SELECT value FROM application_state WHERE key = ${placeholder}`,
+    args: [key],
+  });
+  const row = (result.rows as Array<{ value?: unknown }> | undefined)?.[0];
+  return {
+    present: row !== undefined,
+    session: row === undefined ? null : parseStoredResumableSession(row.value),
+  };
 }
 
 /**
@@ -196,6 +253,8 @@ export async function reapExpiredUploads(
   }));
 
   let failed = 0;
+  let resumableSessionsAborted = 0;
+  let resumableCleanupFailed = 0;
   if (expired.length > 0 && !dryRun) {
     const ids = expired.map((row) => row.id);
     const result = await exec.execute({
@@ -223,16 +282,35 @@ export async function reapExpiredUploads(
     failed = terminated.size;
 
     for (const id of terminated) {
-      const generationId = expired.find(
-        (row) => row.id === id,
-      )?.uploadGenerationId;
+      const generationId =
+        expired.find((row) => row.id === id)?.uploadGenerationId ?? null;
+      const sessionKey = resumableSessionKey(id, generationId);
+      const sessionState = await readResumableSessionState(
+        exec,
+        p(1),
+        sessionKey,
+      );
+      if (sessionState.present && !sessionState.session) {
+        resumableCleanupFailed += 1;
+        console.warn(
+          `[upload-reaper-${id}] resumable session state is unreadable; keeping it for manual cleanup`,
+        );
+        continue;
+      }
+      if (sessionState.session) {
+        const cleaned = await abortResumableUploadSession(
+          sessionState.session,
+          { label: `upload-reaper-${id}` },
+        );
+        if (!cleaned) {
+          resumableCleanupFailed += 1;
+          continue;
+        }
+        resumableSessionsAborted += 1;
+      }
       await exec.execute({
         sql: `DELETE FROM application_state WHERE key = ${p(1)}`,
-        args: [
-          generationId
-            ? `resumable-session-${id}-${generationId}`
-            : `resumable-session-${id}`,
-        ],
+        args: [sessionKey],
       });
     }
   }
@@ -241,7 +319,14 @@ export async function reapExpiredUploads(
     ? (await selectUnclaimedChunkKeys(limit)).length
     : await deleteUnclaimedChunkScratch(limit);
 
-  return { dryRun, expired, failed, scratchKeysDeleted };
+  return {
+    dryRun,
+    expired,
+    failed,
+    scratchKeysDeleted,
+    resumableSessionsAborted,
+    resumableCleanupFailed,
+  };
 }
 
 /**

package/corpus/templates/clips/server/routes/api/agent-context.json.get.ts

@@ -6,6 +6,7 @@
  * smaller agent-oriented shape plus discoverable transcript/frame APIs.
  */
 
+import { asc, count, eq } from "drizzle-orm";
 import {
   defineEventHandler,
   getQuery,
@@ -13,6 +14,7 @@ import {
   type H3Event,
 } from "h3";
 
+import { getDb, schema } from "../../db/index.js";
 import {
   applyAgentJsonHeaders,
   buildPublicAgentContext,
@@ -21,6 +23,7 @@ import {
   loadAgentCtas,
   loadAgentTranscript,
   loadPublicAgentAccess,
+  MAX_PUBLIC_AGENT_HISTORY_ITEMS,
   parseAgentChapters,
   queryString,
   CLIPS_AGENT_ACCESS_PARAM,
@@ -42,14 +45,76 @@ export default defineEventHandler(async (event: H3Event) => {
   }
 
   const recording = accessResult.access.recording;
-  const [{ transcript, agentSegments }, ctas, browserDiagnostics, bugReport] =
-    await Promise.all([
-      loadAgentTranscript(recording.id, recording.durationMs),
-      loadAgentCtas(recording.id),
-      loadAgentBrowserDiagnostics(recording.id),
-      loadAgentBugReport(recording.id),
-    ]);
+  const db = getDb();
+  const historyQueryLimit = MAX_PUBLIC_AGENT_HISTORY_ITEMS + 1;
+  const [
+    { transcript, agentSegments },
+    commentRows,
+    reactionRows,
+    commentCountRows,
+    reactionCountRows,
+    ctas,
+    browserDiagnostics,
+    bugReport,
+  ] = await Promise.all([
+    loadAgentTranscript(recording.id, recording.durationMs),
+    recording.enableComments
+      ? db
+          .select({
+            id: schema.recordingComments.id,
+            recordingId: schema.recordingComments.recordingId,
+            threadId: schema.recordingComments.threadId,
+            parentId: schema.recordingComments.parentId,
+            authorName: schema.recordingComments.authorName,
+            content: schema.recordingComments.content,
+            videoTimestampMs: schema.recordingComments.videoTimestampMs,
+            resolved: schema.recordingComments.resolved,
+            createdAt: schema.recordingComments.createdAt,
+            updatedAt: schema.recordingComments.updatedAt,
+          })
+          .from(schema.recordingComments)
+          .where(eq(schema.recordingComments.recordingId, recording.id))
+          .orderBy(
+            asc(schema.recordingComments.videoTimestampMs),
+            asc(schema.recordingComments.createdAt),
+          )
+          .limit(historyQueryLimit)
+      : Promise.resolve([]),
+    recording.enableReactions
+      ? db
+          .select({
+            id: schema.recordingReactions.id,
+            emoji: schema.recordingReactions.emoji,
+            videoTimestampMs: schema.recordingReactions.videoTimestampMs,
+            viewerName: schema.recordingReactions.viewerName,
+            createdAt: schema.recordingReactions.createdAt,
+          })
+          .from(schema.recordingReactions)
+          .where(eq(schema.recordingReactions.recordingId, recording.id))
+          .orderBy(asc(schema.recordingReactions.createdAt))
+          .limit(historyQueryLimit)
+      : Promise.resolve([]),
+    recording.enableComments
+      ? db
+          .select({ count: count() })
+          .from(schema.recordingComments)
+          .where(eq(schema.recordingComments.recordingId, recording.id))
+      : Promise.resolve([{ count: 0 }]),
+    recording.enableReactions
+      ? db
+          .select({ count: count() })
+          .from(schema.recordingReactions)
+          .where(eq(schema.recordingReactions.recordingId, recording.id))
+      : Promise.resolve([{ count: 0 }]),
+    loadAgentCtas(recording.id),
+    loadAgentBrowserDiagnostics(recording.id),
+    loadAgentBugReport(recording.id),
+  ]);
   const chapters = parseAgentChapters(recording);
+  const comments = commentRows.slice(0, MAX_PUBLIC_AGENT_HISTORY_ITEMS);
+  const reactions = reactionRows.slice(0, MAX_PUBLIC_AGENT_HISTORY_ITEMS);
+  const commentCount = Number(commentCountRows[0]?.count ?? comments.length);
+  const reactionCount = Number(reactionCountRows[0]?.count ?? reactions.length);
 
   return buildPublicAgentContext({
     event,
@@ -57,6 +122,16 @@ export default defineEventHandler(async (event: H3Event) => {
     transcript,
     agentSegments,
     chapters,
+    comments,
+    reactions,
+    commentCount,
+    commentsTruncated:
+      commentRows.length > MAX_PUBLIC_AGENT_HISTORY_ITEMS ||
+      commentCount > comments.length,
+    reactionCount,
+    reactionsTruncated:
+      reactionRows.length > MAX_PUBLIC_AGENT_HISTORY_ITEMS ||
+      reactionCount > reactions.length,
     ctas,
     browserDiagnostics,
     bugReport,

package/corpus/templates/clips/server/routes/api/public-recording.get.ts

@@ -263,6 +263,7 @@ export default defineEventHandler(async (event) => {
     !viewerIsOrgMember &&
     !tokenAllowsAgentAccess
   ) {
+    setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
     setResponseStatus(event, 404);
     return { error: "Not found" };
   }

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -52,6 +52,7 @@ import {
   setResumableSession,
   type StoredResumableSession,
 } from "../../../../lib/resumable-session.js";
+import { abortResumableUploadSession } from "../../../../lib/resumable-upload-cleanup.js";
 import { resolveResumableUploadProvider } from "../../../../lib/resumable-upload-provider.js";
 import { isStreamingUploadDisabled } from "../../../../lib/streaming-upload-mode.js";
 import { renewUploadLease } from "../../../../lib/upload-lease.js";
@@ -854,6 +855,23 @@ async function handleResumableChunk(
     `[resumable-chunk-${recordingId}] resumable session exists - bytesUploaded=${session.bytesUploaded} index=${index} isFinal=${isFinal}`,
   );
 
+  const cleanupFailedFinalSession = async () => {
+    const cleaned = await abortResumableUploadSession(session, {
+      provider: uploadProvider,
+      label: `resumable-final-${recordingId}`,
+    });
+    if (cleaned) {
+      await deleteResumableSession(recordingId, uploadGenerationId).catch(
+        (error) =>
+          console.warn(
+            `[resumable-chunk-${recordingId}] failed to retire aborted session:`,
+            error,
+          ),
+      );
+    }
+    return !cleaned;
+  };
+
   const raw = await readRawBody(event, false);
   const bytes: Uint8Array = raw ?? new Uint8Array(0);
   let finalizedSourceSizeBytes = session.bytesUploaded;
@@ -884,19 +902,37 @@ async function handleResumableChunk(
     // 0-byte sentinel from the recorder after stop(). All data chunks have
     // already been PUT to the provider; send Content-Range: bytes */<total>
     // to close the session before handing off to finalize-recording.
-    const closeRes = await uploadProvider.resumable.relayChunk(
-      { sessionId: session.sessionId, meta: session.meta },
-      `bytes */${session.bytesUploaded}`,
-      new Uint8Array(0),
-    );
+    let closeRes;
+    try {
+      closeRes = await uploadProvider.resumable.relayChunk(
+        { sessionId: session.sessionId, meta: session.meta },
+        `bytes */${session.bytesUploaded}`,
+        new Uint8Array(0),
+      );
+    } catch (error) {
+      const cleanupFailed = await cleanupFailedFinalSession();
+      const detail = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[resumable-chunk-${recordingId}] session close threw:`,
+        error,
+      );
+      setResponseStatus(event, 502);
+      return {
+        ok: false,
+        error: `Resumable session close failed: ${detail}`,
+        ...(cleanupFailed ? { cleanupFailed: true } : {}),
+      };
+    }
     if (!closeRes.ok || closeRes.status === 308) {
       console.error(
         `[resumable-chunk-${recordingId}] session close failed (${closeRes.status})`,
       );
+      const cleanupFailed = await cleanupFailedFinalSession();
       setResponseStatus(event, 502);
       return {
         ok: false,
         error: `Resumable session close failed (${closeRes.status})`,
+        ...(cleanupFailed ? { cleanupFailed: true } : {}),
       };
     }
     if (closeRes.updatedMeta) {
@@ -964,12 +1000,31 @@ async function handleResumableChunk(
         : `bytes ${start}-${end}/*`;
 
       const putT0 = Date.now();
-      const putResult = await uploadProvider.resumable.relayChunk(
-        { sessionId: session.sessionId, meta: session.meta },
-        contentRange,
-        bytes,
-        { mimeType: mimeType.split(";")[0].trim() },
-      );
+      let putResult;
+      try {
+        putResult = await uploadProvider.resumable.relayChunk(
+          { sessionId: session.sessionId, meta: session.meta },
+          contentRange,
+          bytes,
+          { mimeType: mimeType.split(";")[0].trim() },
+        );
+      } catch (error) {
+        if (isFinal) {
+          const cleanupFailed = await cleanupFailedFinalSession();
+          const detail = error instanceof Error ? error.message : String(error);
+          console.error(
+            `[resumable-chunk-${recordingId}] final chunk upload threw:`,
+            error,
+          );
+          setResponseStatus(event, 502);
+          return {
+            ok: false,
+            error: `Final chunk upload failed: ${detail}`,
+            ...(cleanupFailed ? { cleanupFailed: true } : {}),
+          };
+        }
+        throw error;
+      }
       console.log(
         `[resumable-chunk-${recordingId}] PUT ${Date.now() - putT0}ms status=${putResult.status} range="${contentRange}"`,
       );
@@ -980,7 +1035,10 @@ async function handleResumableChunk(
       if (!resultOk) {
         const restartRequired =
           putResult.status === 404 || putResult.status === 410;
-        if (restartRequired) {
+        const cleanupFailed = isFinal
+          ? await cleanupFailedFinalSession()
+          : false;
+        if (restartRequired && !cleanupFailed) {
           await deleteResumableSession(recordingId, uploadGenerationId).catch(
             () => {},
           );
@@ -990,6 +1048,7 @@ async function handleResumableChunk(
           ok: false,
           error: `Chunk upload failed (${putResult.status})`,
           ...(restartRequired ? { restartRequired: true } : {}),
+          ...(cleanupFailed ? { cleanupFailed: true } : {}),
         };
       }
 

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/interrupt.post.ts

@@ -31,7 +31,7 @@ import {
 } from "../../../../lib/recordings.js";
 import {
   isRetryableUploadInterruption,
-  RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+  retryableUploadInterruptionReason,
 } from "../../../../lib/upload-interruption.js";
 import abortUpload from "./abort.post.js";
 
@@ -131,12 +131,13 @@ export default defineEventHandler(async (event: H3Event) => {
     const uploadStateRaw = await readAppState(uploadStateKey);
     const uploadState = uploadStateRaw ?? {};
     const interruptedAt = new Date().toISOString();
+    const failureReason = retryableUploadInterruptionReason(interruptionDetail);
     if (!alreadyInterrupted) {
       const interrupted = await db
         .update(schema.recordings)
         .set({
           status: "failed",
-          failureReason: RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+          failureReason,
           updatedAt: interruptedAt,
         })
         .where(
@@ -167,7 +168,7 @@ export default defineEventHandler(async (event: H3Event) => {
         ...uploadState,
         recordingId,
         status: "failed",
-        failureReason: RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+        failureReason,
         retryableInterruption: true,
         uploadAttemptId: attemptId,
         uploadGenerationId,

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/reset-chunks.post.ts

@@ -55,8 +55,10 @@ import {
 } from "../../../../lib/recordings.js";
 import {
   deleteResumableSession,
+  getResumableSession,
   setResumableSession,
 } from "../../../../lib/resumable-session.js";
+import { abortResumableUploadSession } from "../../../../lib/resumable-upload-cleanup.js";
 import { shouldEnableStreamingUpload } from "../../../../lib/streaming-upload-mode.js";
 import {
   renewUploadLease,
@@ -217,6 +219,10 @@ export default defineEventHandler(async (event: H3Event) => {
     const nextGenerationId = useGenerationFence ? randomUUID() : null;
     const uploadStateKey = `recording-upload-${recordingId}`;
     const uploadStateSnapshot = await readAppState(uploadStateKey);
+    const discardedResumableSession = await getResumableSession(
+      recordingId,
+      existingGenerationId,
+    );
     const reset = await db
       .update(schema.recordings)
       .set({
@@ -251,6 +257,19 @@ export default defineEventHandler(async (event: H3Event) => {
       };
     }
 
+    if (discardedResumableSession) {
+      const cleaned = await abortResumableUploadSession(
+        discardedResumableSession,
+        { label: `reset-${recordingId}` },
+      );
+      if (!cleaned) {
+        setResponseStatus(event, 502);
+        return {
+          error:
+            "The previous recording upload could not be cleaned up. Retry the upload restart.",
+        };
+      }
+    }
     const cleared = await deleteRecordingChunks(
       ownerEmail,
       recordingId,

package/corpus/templates/clips/server/routes/api/uploads/reap.post.ts

@@ -59,10 +59,17 @@ export default defineEventHandler(async (event: H3Event) => {
   const result = await reapExpiredUploads({
     dryRun: query.dryRun === "1" || query.dryRun === "true",
   });
-  if (result.failed > 0 || result.scratchKeysDeleted > 0) {
+  if (
+    result.failed > 0 ||
+    result.scratchKeysDeleted > 0 ||
+    result.resumableSessionsAborted > 0 ||
+    result.resumableCleanupFailed > 0
+  ) {
     console.log("[uploads] reaped expired uploads", {
       failed: result.failed,
       scratchKeysDeleted: result.scratchKeysDeleted,
+      resumableSessionsAborted: result.resumableSessionsAborted,
+      resumableCleanupFailed: result.resumableCleanupFailed,
     });
   }
   return { ok: true, ...result };

package/corpus/templates/clips/shared/recording-link.ts

@@ -12,6 +12,10 @@
  */
 import { withShareAttribution } from "./share-attribution";
 
+/** Short-lived capability used by a signed-in private share viewer to request access. */
+export const CLIPS_ACCESS_REQUEST_TOKEN_PREFIX = "clips-access-request";
+export const CLIPS_ACCESS_REQUEST_TOKEN_TTL_SECONDS = 10 * 60;
+
 /** Public share path for a recording, relative to the app base path. */
 export function recordingSharePath(recordingId: string): string {
   return `/share/${encodeURIComponent(recordingId)}`;

package/corpus/templates/clips/shared/share-loader-response.ts

@@ -5,8 +5,9 @@ export const PRIVATE_SHARE_RESPONSE_HEADERS = {
   "Referrer-Policy": "no-referrer",
 };
 
-export function privateShareLoaderData<T>(payload: T) {
+export function privateShareLoaderData<T>(payload: T, status = 200) {
   return data(payload, {
+    status,
     headers: PRIVATE_SHARE_RESPONSE_HEADERS,
   });
 }

package/corpus/templates/content/app/components/editor/DocumentToolbar.tsx

@@ -6,6 +6,7 @@ import { useT } from "@agent-native/core/client/i18n";
 import { ShareButton } from "@agent-native/core/client/sharing";
 import { CreativeContextShareTab } from "@agent-native/creative-context/client";
 import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { ShareTrigger } from "@agent-native/toolkit/sharing";
 import type { DocumentSourceInfo } from "@shared/api";
 import {
   IconArrowBarDown,
@@ -31,7 +32,6 @@ import {
   IconLink,
   IconMessageCircle,
   IconRefresh,
-  IconShare3,
   IconTrash,
 } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
@@ -891,22 +891,13 @@ export function DocumentToolbar({
             className="mr-1"
           />
           {isLocalFileDocument ? (
-            <Button
-              size="sm"
-              variant="outline"
-              className="h-9 gap-1.5 rounded-lg px-3"
+            <ShareTrigger
+              className="h-9 rounded-lg px-3"
+              pending={shareLocalFile.isPending}
               disabled={shareLocalFile.isPending}
-              onClick={() => void handleShareLocalFile()}
-            >
-              {shareLocalFile.isPending ? (
-                <IconLoader2 className="h-4 w-4 animate-spin" />
-              ) : (
-                <IconShare3 className="h-4 w-4" />
-              )}
-              <span className="hidden sm:inline">
-                {t("editor.toolbar.share")}
-              </span>
-            </Button>
+              label={t("editor.toolbar.share")}
+              onPress={() => void handleShareLocalFile()}
+            />
           ) : (
             <>
               <ShareButton

package/corpus/templates/factory/AGENTS.md

@@ -35,7 +35,8 @@ decisions, feedback, agent runs, and provider audit records.
 
 ## Application state
 
-- `navigation.view`: `factory` when the workspace is open.
+- `navigation.view`: `factory` for the Factory workspace or `agents` for the
+  shared Agents sidebar surface.
 - `navigation.factoryId`: selected Factory id when present.
 - `navigation.factoryTab`: `map` | `inbox` | `rules` | `automations` | `agents` | `audit` | `settings`.
 - `navigation.factoryAuditRunId`: selected automation run in the audit view when present.
@@ -43,6 +44,9 @@ decisions, feedback, agent runs, and provider audit records.
 - A selected graph node or edge is part of `navigation` context. Read
   `view-screen` before answering why a route exists or changing the selected
   Factory.
+- The `/agents` surface shows mounted agentic apps and reusable agent packs from
+  the same Dispatch SQL/action registry. Use `view-screen` there before
+  answering questions about the visible agent inventory.
 
 ## Action contract