Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/inbox-e2e.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@ on:
- 'packages/shared/inbox/**'
- 'packages/core/inbox*'
- 'packages/shared/config.ts'
- 'packages/server/html-assets.ts'
- 'packages/shared/html-assets.ts'
- 'packages/shared/html-assets-node.ts'
- 'packages/ui/**'
- 'apps/hook/server/index.ts'
- 'apps/hook/server/inbox*'
Expand All @@ -37,6 +40,9 @@ on:
- 'packages/shared/inbox/**'
- 'packages/core/inbox*'
- 'packages/shared/config.ts'
- 'packages/server/html-assets.ts'
- 'packages/shared/html-assets.ts'
- 'packages/shared/html-assets-node.ts'
- 'packages/ui/**'
- 'apps/hook/server/index.ts'
- 'apps/hook/server/inbox*'
Expand Down
20 changes: 15 additions & 5 deletions AGENTS.md

Large diffs are not rendered by default.

155 changes: 155 additions & 0 deletions packages/core/inbox-attachments.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
/**
* Plannotator Inbox attachments: the browser-safe shapes and the file rules
* that need no filesystem.
*
* An agent attaches files to a message by path (`send_message`'s
* `attachments`). At send time the Inbox records each file's absolute
* realpath, copies its bytes into a content-addressed blob
* (`inbox/blobs/<sha256>`, the version it sent) and writes one attachment
* record on the message. The window and agents reach a file ONLY by its
* attachment id, never by a path: the current file as it is on disk now, or
* the sent version from the blob. Annotate's file rules apply, without its
* size bound (owner, 2026-10-06: no caps): the annotatable extension set,
* `.env` refused, regular files only.
*
* The person's annotations on an attachment are stored per attachment and
* version (`inbox/projects/<key>/annotations.jsonl`): `version` is "current"
* (the file on disk, whatever its bytes are now, so a draft survives the
* agent's edit and re-anchors by its text, the #1710 lesson) or the sent
* blob's sha256.
*/

import { diagramRenderKindForPath, isAnnotatableDocPath } from "./annotatable";
import { ulid } from "./inbox-types";

/** How the window draws a file: Plannotator's viewer for its type. */
export type InboxAttachmentKind = "markdown" | "text" | "html" | "mermaid" | "graphviz";

export interface InboxAttachment {
/** `att_<ULID>`. */
id: string;
/** The file's absolute realpath at send time: the only path ever read. */
path: string;
/** The path as the agent named it (absolute) when it differs from `path` (a symlink). */
named_path: string | null;
/** The file name, for display. */
name: string;
kind: InboxAttachmentKind;
/** The sha256 of the bytes sent: the blob `inbox/blobs/<sent_sha256>`. */
sent_sha256: string;
/** Size in bytes of the sent version. */
size: number;
/** When it was sent (the message's time). */
sent_at: string;
/** The file's mtime when it was sent. */
sent_mtime: string;
}

/** Why the current file cannot be opened (the sent version always can). */
export type InboxAttachmentUnavailable =
| { code: "attachment_missing"; message: string }
| { code: "attachment_changed_type"; message: string };

/** An attachment as the window reads it: the record plus the file as it is now. */
export interface InboxAttachmentState extends InboxAttachment {
message_id: string;
/** The file on disk now, or null when it cannot be opened (`unavailable` says why). */
current: { sha256: string; size: number; mtime: string } | null;
/** The current bytes differ from the sent ones. */
changed_since_sent: boolean;
unavailable: InboxAttachmentUnavailable | null;
}

/** "current", or the sent blob's sha256. */
export type InboxAnnotationVersion = string;

/** One annotation of the person's on an attachment, stored until it rides a Send. */
export interface InboxAnnotationRecord {
/** The annotation's own id (Plannotator's `Annotation.id`). */
id: string;
project_id: string;
thread_id: string;
message_id: string;
attachment_id: string;
/** The attachment's realpath: with `version`, the draft's key. */
path: string;
version: InboxAnnotationVersion;
/** Plannotator's `Annotation`, as the viewer made it (opaque to the store). */
annotation: Record<string, unknown>;
created_at: string;
updated_at: string;
removed_at: string | null;
/** The person's reply that carried it, or null while it waits for a Send. */
sent_reply_id: string | null;
}

export const INBOX_ANNOTATION_CURRENT = "current";

const ATTACHMENT_ID_RE = /^att_[0-9A-HJKMNP-TV-Z]{26}$/;
/** An annotation id the viewer mints: short, and safe in a URL path segment. */
const ANNOTATION_ID_RE = /^[A-Za-z0-9_.:-]{1,200}$/;
const SHA256_RE = /^[0-9a-f]{64}$/;

export function inboxAttachmentId(now?: number): string {
return `att_${ulid(now)}`;
}

export function isInboxAttachmentId(value: unknown): value is string {
return typeof value === "string" && ATTACHMENT_ID_RE.test(value);
}

export function isInboxAnnotationId(value: unknown): value is string {
return typeof value === "string" && ANNOTATION_ID_RE.test(value);
}

export function isInboxAnnotationVersion(value: unknown): value is InboxAnnotationVersion {
return value === INBOX_ANNOTATION_CURRENT || (typeof value === "string" && SHA256_RE.test(value));
}

function baseName(path: string): string {
const parts = path.split(/[\\/]/);
return parts[parts.length - 1] ?? path;
}

/**
* Annotate's file rules on a name, without the size bound: `.env` is refused
* (it holds secrets, and the Inbox keeps a copy of what it was sent), and only
* the annotatable extensions open (plain text, config and data formats,
* diagram sources, HTML). Null when the name passes.
*/
export function inboxAttachmentNameRefusal(path: string): string | null {
const name = baseName(path);
if (name === ".env" || /^\.env$/i.test(name)) return ".env files are never attached (they hold secrets).";
if (!isAnnotatableDocPath(name)) {
return "not a file the Inbox can open (markdown, plain text, config and data files, Mermaid and Graphviz sources, HTML).";
}
return null;
}

/** The viewer for a file, by its extension. */
export function inboxAttachmentKind(path: string): InboxAttachmentKind {
const name = baseName(path);
if (/\.html?$/i.test(name)) return "html";
const diagram = diagramRenderKindForPath(name);
if (diagram) return diagram;
if (/\.mdx?$/i.test(name)) return "markdown";
return "text";
}

/** The kind as a tile names it: "Markdown", "HTML", "Mermaid". */
export function inboxAttachmentKindLabel(kind: InboxAttachmentKind, name: string): string {
switch (kind) {
case "markdown":
return "Markdown";
case "html":
return "HTML";
case "mermaid":
return "Mermaid";
case "graphviz":
return "Graphviz";
case "text": {
const ext = /\.([A-Za-z0-9]+)$/.exec(name)?.[1];
return ext && ext.toLowerCase() !== "txt" ? ext.toUpperCase() : "Text";
}
}
}
16 changes: 14 additions & 2 deletions packages/core/inbox-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@
*/

import type { QuestionAnswer, QuestionKind } from "./question-block";
import type { InboxAnnotationRecord, InboxAttachment } from "./inbox-attachments";

// The attachment shapes and file rules (step 2) live in their own module and
// reach the Inbox through this published entry, so core's export map is unchanged.
export * from "./inbox-attachments";

/** Every record and line carries this version. Fields are only ever added. */
export const INBOX_RECORD_VERSION = 1 as const;
Expand Down Expand Up @@ -185,6 +190,12 @@ export interface InboxMessage {
*/
agent_checked_seq?: number | null;
agent_checked_at?: string | null;
/**
* The files an agent attached (send_message's `attachments`), recorded at
* send time and read only by their ids (see inbox-attachments.ts). Added in
* step 2: older records lack it.
*/
attachments?: InboxAttachment[];
}

/** One choice as the wire serves it (Workspaces' `QuestionChoice`). */
Expand Down Expand Up @@ -424,14 +435,15 @@ export interface InboxDecision {

// ─────────────────────────────── Lines ───────────────────────────────

export type InboxRecordKind = "project" | "message" | "question" | "decision";
export type InboxRecordKind = "project" | "message" | "question" | "decision" | "annotation";

/** One line of the store: a full snapshot of one record. */
export type InboxLine =
| { v: 1; seq: number; at: string; kind: "project"; id: string; record: InboxProject }
| { v: 1; seq: number; at: string; kind: "message"; id: string; record: InboxMessage }
| { v: 1; seq: number; at: string; kind: "question"; id: string; record: InboxQuestionRecord }
| { v: 1; seq: number; at: string; kind: "decision"; id: string; record: InboxDecision };
| { v: 1; seq: number; at: string; kind: "decision"; id: string; record: InboxDecision }
| { v: 1; seq: number; at: string; kind: "annotation"; id: string; record: InboxAnnotationRecord };

// ─────────────────────────────── Health ───────────────────────────────

Expand Down
66 changes: 61 additions & 5 deletions packages/inbox/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,29 @@ import { DecisionsPage } from './components/Decisions';

// The Inbox has no /api/config and no browser-agent tools: settings stay in
// the page's own cookies, and WebMCP is off.
configurePlannotatorUI({ serverSync: () => {}, webmcp: { enabled: false, namePrefix: 'plannotator.' } });
// No image uploads and no skill catalog either: a comment's image would need
// an upload route the Inbox does not have, so the composer says so instead of
// posting nowhere.
configurePlannotatorUI({
serverSync: () => {},
webmcp: { enabled: false, namePrefix: 'plannotator.' },
// Skill references in comments read the host's skills; the Inbox has none to offer.
skillCatalogTransport: async () => [],
uploadTransport: {
upload: async () => {
throw new Error('Images cannot be added to a comment in the Inbox.');
},
},
});

interface Route {
page: 'inbox' | 'settings' | 'decisions';
project: string | null;
thread: string | null;
/** The decision open beside the Decisions list. */
decision?: string | null;
/** An attachment open beside the thread: `file=att_…`, `v=sent` for the version the agent sent, `at=` an annotation to show. */
file?: { id: string; version: 'current' | 'sent'; focus: string | null } | null;
}

function readRoute(): Route {
Expand All @@ -55,7 +70,14 @@ function readRoute(): Route {
if (params.has('decisions')) {
return { page: 'decisions', project: params.get('decisions') || null, thread: null, decision: params.get('decision') };
}
return { page: 'inbox', project: params.get('project'), thread: params.get('thread') };
const thread = params.get('thread');
const fileId = thread ? params.get('file') : null;
return {
page: 'inbox',
project: params.get('project'),
thread,
file: fileId ? { id: fileId, version: params.get('v') === 'sent' ? 'sent' : 'current', focus: params.get('at') } : null,
};
}

function writeRoute(route: Route): void {
Expand All @@ -70,6 +92,11 @@ function writeRoute(route: Route): void {
const params = new URLSearchParams();
if (route.project) params.set('project', route.project);
if (route.thread) params.set('thread', route.thread);
if (route.thread && route.file) {
params.set('file', route.file.id);
if (route.file.version === 'sent') params.set('v', 'sent');
if (route.file.focus) params.set('at', route.file.focus);
}
hash = params.toString();
}
const next = hash ? `#${hash}` : window.location.pathname + window.location.search;
Expand Down Expand Up @@ -248,7 +275,8 @@ function Inbox() {

useEffect(() => {
const onKey = (event: KeyboardEvent) => {
if (event.key !== 'Escape' || !routeRef.current.thread) return;
// An open file owns Escape (the HTML viewer's ladder, the composers).
if (event.key !== 'Escape' || !routeRef.current.thread || routeRef.current.file) return;
const target = event.target as HTMLElement | null;
if (target && (target.tagName === 'TEXTAREA' || target.tagName === 'INPUT' || target.isContentEditable)) return;
writeRoute({ ...routeRef.current, thread: null });
Expand Down Expand Up @@ -318,6 +346,26 @@ function Inbox() {
}
};

// Settings' Delete thread / Delete project: the store, its blobs and the size read again.
const deleteThread = async (threadId: string) => {
setSettingsError(null);
try {
await inboxApi.deleteThread(threadId);
} catch (cause) {
setSettingsError(cause instanceof Error ? cause.message : 'The thread was not deleted.');
}
await Promise.all([refreshSettings(), refreshList(true)]);
};
const deleteProject = async (projectId: string) => {
setSettingsError(null);
try {
await inboxApi.deleteProject(projectId);
} catch (cause) {
setSettingsError(cause instanceof Error ? cause.message : 'The project was not deleted.');
}
await Promise.all([refreshSettings(), refreshList(true)]);
};

const projects = latest?.projects ?? [];
const latestSections = latest?.sections ?? [];
const projectCounts = useMemo(() => {
Expand All @@ -344,6 +392,8 @@ function Inbox() {
const filterProject = route.page === 'inbox' && route.project ? projects.find((p) => p.id === route.project) ?? null : null;
const notice = shown && latest ? heldNotice(filterSections(shown, route.project), filterSections(latest.sections, route.project)).text : null;
const firstRun = latest !== null && projects.length === 0;
// A file beside the thread takes the list's and the sidebar's room (record 2.2).
const fileOpen = route.page === 'inbox' && !!route.thread && !!route.file;

let main: ReactNode;
const decisionsFolder = decisionsProject ? projects.find((p) => p.id === decisionsProject) ?? null : null;
Expand All @@ -356,6 +406,8 @@ function Inbox() {
onToggleTool={toggleTool}
permission={notifications.permission}
onToggleNotifications={(next) => void notifications.setEnabled(next)}
onDeleteThread={deleteThread}
onDeleteProject={deleteProject}
/>
);
} else if (route.page === 'decisions' && decisionsFolder) {
Expand All @@ -382,6 +434,7 @@ function Inbox() {
} else {
main = (
<>
{!fileOpen && (
<InboxList
title={filterProject?.name ?? 'Inbox'}
path={filterProject ? tildePath(filterProject.root, settings?.home) : null}
Expand All @@ -394,15 +447,18 @@ function Inbox() {
onShowNew={() => setShown(latest.sections)}
onOpen={openRow}
/>
)}
{route.thread && thread && thread.thread_id === route.thread && (
<ThreadPane
thread={thread}
sent={latestSections.flatMap((section) => section.threads).find((row) => row.thread_id === thread.thread_id)?.sent ?? null}
onQuestions={patchQuestions}
onChanged={afterWrite}
onClose={() => go({ ...route, thread: null })}
onClose={() => go({ ...route, thread: null, file: null })}
decisions={threadDecisions}
onOpenDecisionPage={(decision) => go({ page: 'decisions', project: decision.project_id, thread: null, decision: decision.id })}
file={route.file ?? null}
onOpenFile={(file) => writeRoute({ ...routeRef.current, file })}
/>
)}
</>
Expand All @@ -411,7 +467,7 @@ function Inbox() {

return (
<div className="pn-inbox">
<div className="ib-shell">
<div className={`ib-shell${fileOpen ? ' ib-fileopen' : ''}`}>
<Sidebar
page={route.page}
projectId={route.project}
Expand Down
Loading
Loading