Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Add agent-settable session emoji statuses (#1475)

Regan Bellb29fda25baad
diff --git a/docs/screenshots/session-status/desktop.png b/docs/screenshots/session-status/desktop.png
new file mode 100644
index 000000000..2d79668c6
Binary files /dev/null and b/docs/screenshots/session-status/desktop.png differ
diff --git a/docs/screenshots/session-status/mobile.png b/docs/screenshots/session-status/mobile.png
new file mode 100644
index 000000000..9c1c92b4d
Binary files /dev/null and b/docs/screenshots/session-status/mobile.png differ
diff --git a/plugins/web-ui/src/chat.ts b/plugins/web-ui/src/chat.ts
index b80ff16b8..81a7afe69 100644
--- a/plugins/web-ui/src/chat.ts
+++ b/plugins/web-ui/src/chat.ts
@@ -1478,6 +1478,7 @@ export function createChatSurface(
? chatState.forkSession.forkedFrom
: undefined;
return sessionTopbarTpl({
+ status: session?.status,
sessionId: chatState.sessionId ?? session?.id,
crumb,
title,
diff --git a/plugins/web-ui/src/conversations.ts b/plugins/web-ui/src/conversations.ts
index 1ec7f69c4..d8743e6c6 100644
--- a/plugins/web-ui/src/conversations.ts
+++ b/plugins/web-ui/src/conversations.ts
@@ -88,7 +88,11 @@ export function ensureDeliveryStream(): void {
for (const conv of live) conv.onDelivery(threadRef);
},
(event) => {
- const { list, matched } = applySessionState(sessionsState.list, event);
+ if (event.state === "metadata") {
+ void refreshSessions({ silent: true });
+ return;
+ }
+ const { list, matched } = applySessionState(sessionsState.list, { ...event, state: event.state });
if (matched) {
sessionsState.list = list;
renderList();
diff --git a/plugins/web-ui/src/core-bridge.ts b/plugins/web-ui/src/core-bridge.ts
index 706f06b50..7266cf959 100644
--- a/plugins/web-ui/src/core-bridge.ts
+++ b/plugins/web-ui/src/core-bridge.ts
@@ -125,6 +125,7 @@ export interface DeliveredFile {
}
export interface CoreSession {
+ status?: { emoji: string; text: string } | null;
id: string;
type: "dm" | "channel" | "group";
scopeId: string;
@@ -1422,7 +1423,7 @@ export async function pollRun(
export interface SessionStateEvent {
threadRef: string;
sessionId?: string;
- state: "working" | "awaiting_approval" | "idle";
+ state: "working" | "awaiting_approval" | "idle" | "metadata";
at: number;
}
diff --git a/plugins/web-ui/src/session-scope.ts b/plugins/web-ui/src/session-scope.ts
index 4d103928e..8ae27316f 100644
--- a/plugins/web-ui/src/session-scope.ts
+++ b/plugins/web-ui/src/session-scope.ts
@@ -1,3 +1,5 @@
+import { sessionStatusMark } from "./session-status.ts";
+import type { CoreSession } from "./core-bridge.ts";
import { html, nothing, type TemplateResult } from "lit";
import { ArrowUpLeft, Box, Brain, Clock3, Ellipsis, Files, GitFork, KeyRound, Rocket } from "lucide";
import { api } from "./core-bridge";
@@ -76,6 +78,7 @@ export function scopeToolCount(tool: SessionTool, scope: string, onReady: () =>
export type SessionTool = "crons" | "files" | "memory" | "apps" | "skills" | "keychain";
export interface SessionTopbarOpts {
+ status?: CoreSession["status"];
sessionId?: string | null;
crumb: string | null;
title: string;
@@ -178,6 +181,7 @@ export function sessionTopbarTpl(o: SessionTopbarOpts): TemplateResult {
</button>`
: html`<div class="session-heading">${heading}</div>`
}
+ ${sessionStatusMark(o.status)}
<div class="topbar-actions session-tools">
${tool("crons", Clock3, "Crons")} ${tool("apps", Rocket, "Apps")} ${tool("files", Files, "Files")}
${tool("skills", Box, "Skills")} ${tool("memory", Brain, "Memory")}
diff --git a/plugins/web-ui/src/session-status.ts b/plugins/web-ui/src/session-status.ts
new file mode 100644
index 000000000..4e6c60183
--- /dev/null
+++ b/plugins/web-ui/src/session-status.ts
@@ -0,0 +1,11 @@
+import { html, nothing } from "lit";
+import type { CoreSession } from "./core-bridge.ts";
+import { tip } from "./tooltip.ts";
+
+export function sessionStatusMark(status: CoreSession["status"]) {
+ return status
+ ? html`<span class="session-status" role="img" tabindex="0" aria-label=${status.text} ${tip(status.text)}
+ >${status.emoji}</span
+ >`
+ : nothing;
+}
diff --git a/plugins/web-ui/src/sessions.ts b/plugins/web-ui/src/sessions.ts
index dc5102434..056e2c9fe 100644
--- a/plugins/web-ui/src/sessions.ts
+++ b/plugins/web-ui/src/sessions.ts
@@ -1,3 +1,4 @@
+import { sessionStatusMark } from "./session-status.ts";
import { openSessionShare } from "./session-share";
import { html, nothing, render, type TemplateResult } from "lit";
import { live } from "lit/directives/live.js";
@@ -733,7 +734,7 @@ function chatPageRow(s: CoreSession): TemplateResult {
>
<span class="list-row-title">${statusMarks(s)}<span dir="auto">${groupDmTitle(s)}</span></span>
<span class="list-row-meta">
- ${scopeChip(s.scopeId, s.channelName ?? null)}
+ ${sessionStatusMark(s.status)} ${scopeChip(s.scopeId, s.channelName ?? null)}
${surfaceOf(s) === "slack" ? html`<span class="surface surface-slack">${slackLogo(13)}</span>` : nothing}
${readOnly ? html`<span class="ro-lock" ${tip("Read-only")}>${icon(Lock, 12)}</span>` : nothing}
<span class="list-row-date">${listWhen(activityOf(s))}</span>
@@ -991,7 +992,7 @@ function sessionRow(s: CoreSession, projectChild = false): TemplateResult {
>
${icon(EllipsisVertical, 15)}
</button>
- ${menuOpen ? sessionMenuPopover(s) : nothing}
+ ${sessionStatusMark(s.status)} ${menuOpen ? sessionMenuPopover(s) : nothing}
</div>`
: nothing
}
diff --git a/plugins/web-ui/src/shell.css b/plugins/web-ui/src/shell.css
index de5a9f8d7..74ecd8de2 100644
--- a/plugins/web-ui/src/shell.css
+++ b/plugins/web-ui/src/shell.css
@@ -533,7 +533,7 @@ a.chat-row-open {
box-sizing: border-box;
text-align: left;
- padding: 5px 5px 5px 11px;
+ padding: 5px calc(5px + var(--session-status-space, 0px)) 5px 11px;
border: 0;
border-radius: var(--radius-sm);
background: transparent;
@@ -545,7 +545,7 @@ a.chat-row-open {
.session-row:hover .session,
.session-row:focus-within .session,
.session-row.menu-open .session {
- padding-right: 90px;
+ padding-right: calc(90px + var(--session-status-space, 0px));
}
.session:hover {
background: var(--conversation-hover);
@@ -609,6 +609,28 @@ a.chat-row-open {
white-space: nowrap;
}
+.session-status {
+ display: inline-flex;
+ flex: none;
+ align-items: center;
+ font-size: 14px;
+ line-height: 1;
+}
+
+.session-row:has(.session-status) {
+ --session-status-space: 22px;
+}
+.session-menu > .session-status {
+ justify-content: center;
+ width: 20px;
+}
+.split-pane-title > .session-status {
+ margin-inline-start: auto;
+}
+.split-pane-title:has(> .session-status) .split-tab-actions {
+ right: 22px;
+}
+
.working-mark {
display: inline-flex;
align-items: center;
@@ -5738,7 +5760,7 @@ a.connector-widget:focus-visible {
.session-row:hover .session,
.session-row:focus-within .session,
.session-row.menu-open .session {
- padding-right: 136px;
+ padding-right: calc(136px + var(--session-status-space, 0px));
}
.session-menu {
right: 0;
@@ -10639,7 +10661,7 @@ h3.ambient-field-label {
.session-row:hover .session,
.session-row:focus-within .session,
.session-row.menu-open .session {
- padding-right: 48px;
+ padding-right: calc(48px + var(--session-status-space, 0px));
}
.user-pill {
min-height: 44px;
diff --git a/plugins/web-ui/src/split.ts b/plugins/web-ui/src/split.ts
index d73340d86..985915891 100644
--- a/plugins/web-ui/src/split.ts
+++ b/plugins/web-ui/src/split.ts
@@ -1,3 +1,4 @@
+import { sessionStatusMark } from "./session-status.ts";
import { openSessionShare } from "./session-share";
import { preserveTranscriptScroll } from "./transcript-viewport";
import { html, nothing, render, type TemplateResult } from "lit";
@@ -804,7 +805,7 @@ function computeHeaderSignature(): string {
return (dockApi?.panels ?? [])
.map(
(p) =>
- `${p.id}|${paneSession(p)?.id ?? ""}|${paneCrumb(p) ?? ""}|${paneTitle(p)}|${paneIsWorking(p)}|${paneAwaitsInput(p)}|${paneBackground(p)?.label ?? ""}|${paneKindBadge(p)}|${paneSession(p)?.parentSessionId ?? ""}|${sessionsState.list.find((row) => row.id === paneSession(p)?.parentSessionId)?.title ?? ""}`,
+ `${p.id}|${paneSession(p)?.id ?? ""}|${paneCrumb(p) ?? ""}|${paneTitle(p)}|${JSON.stringify(paneSession(p)?.status ?? null)}|${paneIsWorking(p)}|${paneAwaitsInput(p)}|${paneBackground(p)?.label ?? ""}|${paneKindBadge(p)}|${paneSession(p)?.parentSessionId ?? ""}|${sessionsState.list.find((row) => row.id === paneSession(p)?.parentSessionId)?.title ?? ""}`,
)
.join("~");
}
@@ -1214,6 +1215,7 @@ class PaneTab implements ITabRenderer {
: nothing
}
<span class="split-pane-title-text" dir="auto">${title}</span>
+ ${sessionStatusMark(paneSession(panel)?.status)}
${
this.inStrip
? html`<span class="split-tab-actions">
diff --git a/plugins/web-ui/test/session-scope.test.ts b/plugins/web-ui/test/session-scope.test.ts
index 040886b60..af41a697f 100644
--- a/plugins/web-ui/test/session-scope.test.ts
+++ b/plugins/web-ui/test/session-scope.test.ts
@@ -9,12 +9,14 @@ import type { SessionTool, SessionTopbarOpts } from "../src/session-scope.ts";
const source = readFileSync(new URL("../src/session-scope.ts", import.meta.url), "utf8");
const dom = new JSDOM("<!doctype html><body></body>");
for (const [key, value] of Object.entries({
+ window: dom.window,
document: dom.window.document,
HTMLElement: dom.window.HTMLElement,
customElements: dom.window.customElements,
}))
Object.defineProperty(globalThis, key, { configurable: true, value });
const { html, nothing, render } = await import("lit");
+const { sessionStatusMark } = await import("../src/session-status.ts");
function load(api: (path: string) => Promise<unknown> = async () => ({})) {
return runInNewContext(
@@ -24,6 +26,7 @@ function load(api: (path: string) => Promise<unknown> = async () => ({})) {
{
api,
html,
+ sessionStatusMark,
nothing,
icon: () => nothing,
tip: () => nothing,
@@ -152,3 +155,21 @@ test("zero counts remain hidden in desktop and mobile tools", () => {
render(load().sessionTopbarTpl({ crumb: null, title: "Test", onTool: () => {}, toolCount: () => 0 }), host);
assert.equal(host.querySelectorAll(".session-tool-count").length, 0);
});
+
+test("session status appears after the heading and before tools", () => {
+ const host = document.createElement("div");
+ render(
+ load().sessionTopbarTpl({
+ crumb: null,
+ title: "Release verification",
+ status: { emoji: "πŸš€", text: "Live in production" },
+ onTool: () => {},
+ }),
+ host,
+ );
+ const status = host.querySelector(".session-status")!;
+ assert.equal(status.textContent, "πŸš€");
+ assert.equal(status.getAttribute("aria-label"), "Live in production");
+ assert.ok(status.previousElementSibling?.classList.contains("session-heading"));
+ assert.ok(status.nextElementSibling?.classList.contains("session-tools"));
+});
diff --git a/plugins/web-ui/test/session-status.test.ts b/plugins/web-ui/test/session-status.test.ts
new file mode 100644
index 000000000..a67cd1756
--- /dev/null
+++ b/plugins/web-ui/test/session-status.test.ts
@@ -0,0 +1,30 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { JSDOM } from "jsdom";
+
+const dom = new JSDOM("<div id='root'></div>");
+Object.assign(globalThis, {
+ document: dom.window.document,
+ window: dom.window,
+ HTMLElement: dom.window.HTMLElement,
+ customElements: dom.window.customElements,
+});
+const { render } = await import("lit");
+const { sessionStatusMark } = await import("../src/session-status.ts");
+const root = document.getElementById("root")!;
+
+test("session status renders safe text, exposes a keyboard tooltip, updates and clears", () => {
+ render(sessionStatusMark({ emoji: "βœ…", text: "PR merged <script>" }), root);
+ const mark = root.querySelector<HTMLElement>(".session-status")!;
+ assert.equal(mark.textContent, "βœ…");
+ assert.equal(mark.getAttribute("aria-label"), "PR merged <script>");
+ mark.dispatchEvent(new dom.window.FocusEvent("focus"));
+ assert.equal(document.querySelector(".qm-tooltip")?.textContent, "PR merged <script>");
+ assert.equal(document.querySelector("script"), null);
+ render(sessionStatusMark({ emoji: "πŸš€", text: "Live in production" }), root);
+ assert.equal(mark.textContent, "πŸš€");
+ assert.equal(document.querySelector(".qm-tooltip")?.textContent, "Live in production");
+ render(sessionStatusMark(null), root);
+ assert.equal(root.querySelector(".session-status"), null);
+ assert.equal(document.querySelector(".qm-tooltip.visible"), null);
+});
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index d773449c9..a5773e0a8 100644
--- a/src/api/agent-api-catalog.ts
+++ b/src/api/agent-api-catalog.ts
@@ -373,13 +373,13 @@ const FAMILIES: AgentApiFamily[] = [
method: "GET",
path: "/v1/conversations",
summary:
- "list the asking person's own conversations (id, title, archived, pinned, lastActivityAt) β€” the same list their web sidebar shows",
+ "list the asking person's own conversations (id, title, status, archived, pinned, lastActivityAt) β€” the same list their web sidebar shows",
},
{
method: "POST",
path: "/v1/conversations/:id",
summary:
- "update one of the asking person's conversations β€” body {archived?, pinned?, title?, color?}; archive/unarchive, pin/unpin, rename (null title clears), or set the sidebar color (#rrggbb; null clears). Per-person and reversible; 404 for a conversation not on their list",
+ "update one of the asking person's conversations β€” body {archived?, pinned?, title?, color?, status?}; archive/unarchive, pin/unpin, rename (null title clears), or set the sidebar color (#rrggbb; null clears). Title, archive, pin, and color are per-person. Status is shared by everyone in the session: {emoji: one Unicode emoji, text: 1–200 characters}, or null to clear. Use it for verified milestones, e.g. βœ… PR merged or πŸš€ Live in production, and replace it as work progresses. 404 for a conversation not on their list",
},
{
method: "GET",
diff --git a/src/api/app-sessions.ts b/src/api/app-sessions.ts
index 4e2d0f9d3..495e8fa4f 100644
--- a/src/api/app-sessions.ts
+++ b/src/api/app-sessions.ts
@@ -1,4 +1,5 @@
import { sessionTreeRoot, sessionTreeRunCount, SUBAGENT_TREE_RUN_CAP } from "../sessions/session-syscalls.ts";
+import { isSessionStatus } from "../sessions/session-status.ts";
import type { PendingApprovalRecord } from "../types.ts";
import { orgId as orgIdOf } from "../config.ts";
import { parseScopeId, scopeId } from "../types.ts";
@@ -735,8 +736,25 @@ export function createSessionMethods(
},
async updateSession(sessionId, principalId, patch) {
- if (!(await sessionForViewer(sessionId, principalId))) return null;
- await deps.sessions.updateParticipantView(sessionId, principalId, patch);
+ const session = await sessionForViewer(sessionId, principalId);
+ if (!session) return null;
+ const { status, ...view } = patch;
+ if (status !== undefined) {
+ const participants = await deps.sessions.participantWindowsOf(sessionId);
+ if (!participants.some((p) => p.principalId === principalId && p.validTo === null)) return null;
+ if (!isSessionStatus(status)) throw new Error("invalid session status");
+ await deps.sessions.updateStatus(sessionId, status ? { emoji: status.emoji, text: status.text.trim() } : null);
+ }
+ await deps.sessions.updateParticipantView(sessionId, principalId, view);
+ if (status !== undefined) {
+ deps.sessionStateBus?.emit({
+ threadRef: session.threadRef,
+ sessionId,
+ participants: await deps.sessions.participantsOf(sessionId),
+ state: "metadata",
+ at: Date.now(),
+ });
+ }
return sessionForViewer(sessionId, principalId);
},
diff --git a/src/api/app-types.ts b/src/api/app-types.ts
index c465d80f3..71a3a30bd 100644
--- a/src/api/app-types.ts
+++ b/src/api/app-types.ts
@@ -369,7 +369,13 @@ export interface App {
updateSession(
sessionId: string,
principalId: string,
- patch: { title?: string | null; archived?: boolean; pinned?: boolean; color?: string | null },
+ patch: {
+ title?: string | null;
+ archived?: boolean;
+ pinned?: boolean;
+ color?: string | null;
+ status?: Session["status"];
+ },
): Promise<Session | null>;
regenerateTitle(sessionId: string, principalId: string): Promise<{ title: string | null } | null>;
detachSession(sessionId: string, principalId: string): Promise<{ detached: true } | null>;
diff --git a/src/api/routes/surface.ts b/src/api/routes/surface.ts
index 28783544f..8c9901dc8 100644
--- a/src/api/routes/surface.ts
+++ b/src/api/routes/surface.ts
@@ -1,7 +1,8 @@
+import { isSessionStatus } from "../../sessions/session-status.ts";
import { suggestedActivityRoutes } from "./suggested-activities.ts";
import { runtimeFallback, runtimeConfigBody, webuiModelEnabled } from "../runtime-config.ts";
import { sessionSharingRoutes } from "./session-sharing.ts";
-import type { Grant, ScopeId } from "../../types.ts";
+import type { Grant, ScopeId, Session } from "../../types.ts";
import { parseScopeId, scopeId as makeScopeId } from "../../types.ts";
import type { Skill, SkillResolution } from "../../skills/skill-store.ts";
import { ByteSourceTooLargeError } from "../../files/durable-byte-store.ts";
@@ -371,10 +372,23 @@ async function uploadFile(ctx: ApiCtx): Promise<void> {
async function patchSession(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
- const b = body as { principalId?: unknown; title?: unknown; archived?: unknown; pinned?: unknown; color?: unknown };
+ const b = body as {
+ principalId?: unknown;
+ title?: unknown;
+ archived?: unknown;
+ pinned?: unknown;
+ color?: unknown;
+ status?: unknown;
+ };
const principalId = typeof b.principalId === "string" ? b.principalId : null;
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
- const patch: { title?: string | null; archived?: boolean; pinned?: boolean; color?: string | null } = {};
+ const patch: {
+ title?: string | null;
+ archived?: boolean;
+ pinned?: boolean;
+ color?: string | null;
+ status?: Session["status"];
+ } = {};
if ("title" in b) {
if (b.title !== null && typeof b.title !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "title must be a string or null" });
@@ -400,13 +414,23 @@ async function patchSession(ctx: ApiCtx): Promise<void> {
}
patch.color = typeof b.color === "string" ? b.color.toLowerCase() : null;
}
+ if ("status" in b) {
+ if (!isSessionStatus(b.status)) {
+ return sendJson(res, 400, {
+ error: "bad_request",
+ message: "status must be null or {emoji: one Unicode emoji, text: 1–200 characters without control characters}",
+ });
+ }
+ patch.status = b.status;
+ }
if (
patch.title === undefined &&
patch.archived === undefined &&
patch.pinned === undefined &&
- patch.color === undefined
+ patch.color === undefined &&
+ patch.status === undefined
) {
- return sendJson(res, 400, { error: "bad_request", message: "title, archived, pinned, or color required" });
+ return sendJson(res, 400, { error: "bad_request", message: "title, archived, pinned, color, or status required" });
}
const session = await app.updateSession(id, principalId, patch);
if (!session) return sendJson(res, 404, { error: "not_found" });
@@ -425,6 +449,7 @@ async function listAgentConversations(ctx: ApiCtx): Promise<void> {
scopeId: s.scopeId,
surface: s.surface ?? "unknown",
title: s.title ?? null,
+ status: s.status ?? null,
archived: s.archived === true,
pinned: s.pinned === true,
createdAt: s.createdAt,
@@ -439,7 +464,13 @@ async function patchAgentConversation(ctx: ApiCtx): Promise<void> {
return sendJson(res, 401, { error: "capability_required", message: "this endpoint is for the agent self-API" });
}
const b = isObj(body) ? body : {};
- const patch: { title?: string | null; archived?: boolean; pinned?: boolean; color?: string | null } = {};
+ const patch: {
+ title?: string | null;
+ archived?: boolean;
+ pinned?: boolean;
+ color?: string | null;
+ status?: Session["status"];
+ } = {};
if ("archived" in b) {
if (typeof b.archived !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "archived must be a boolean" });
@@ -465,13 +496,23 @@ async function patchAgentConversation(ctx: ApiCtx): Promise<void> {
}
patch.color = typeof b.color === "string" ? b.color.toLowerCase() : null;
}
+ if ("status" in b) {
+ if (!isSessionStatus(b.status)) {
+ return sendJson(res, 400, {
+ error: "bad_request",
+ message: "status must be null or {emoji: one Unicode emoji, text: 1–200 characters without control characters}",
+ });
+ }
+ patch.status = b.status;
+ }
if (
patch.archived === undefined &&
patch.pinned === undefined &&
patch.title === undefined &&
- patch.color === undefined
+ patch.color === undefined &&
+ patch.status === undefined
) {
- return sendJson(res, 400, { error: "bad_request", message: "archived, pinned, title, or color required" });
+ return sendJson(res, 400, { error: "bad_request", message: "archived, pinned, title, color, or status required" });
}
const session = await app.updateSession(ctx.params.id!, capability.actorId, patch);
if (!session) return sendJson(res, 404, { error: "not_found", message: "not a conversation you can see" });
@@ -489,6 +530,7 @@ async function patchAgentConversation(ctx: ApiCtx): Promise<void> {
archived: session.archived === true,
pinned: session.pinned === true,
color: session.color ?? null,
+ status: session.status ?? null,
},
});
}
diff --git a/src/runs/session-state-bus.ts b/src/runs/session-state-bus.ts
index 63cef22e9..06864ebff 100644
--- a/src/runs/session-state-bus.ts
+++ b/src/runs/session-state-bus.ts
@@ -1,6 +1,6 @@
import { createMemoryEventBus, type EventBus } from "../util/event-bus.ts";
-type SessionState = "working" | "awaiting_approval" | "idle";
+type SessionState = "working" | "awaiting_approval" | "idle" | "metadata";
export interface SessionStateEvent {
threadRef: string;
diff --git a/src/sessions/memory-session-store.ts b/src/sessions/memory-session-store.ts
index 5b278671c..704b3c370 100644
--- a/src/sessions/memory-session-store.ts
+++ b/src/sessions/memory-session-store.ts
@@ -160,6 +160,11 @@ export function createMemorySessionStore(opts: StoreOptions = {}): SessionStore
if (s) s.title = title;
},
+ async updateStatus(sessionId, status) {
+ const s = sessions.get(sessionId);
+ if (s) s.status = status ? { ...status } : null;
+ },
+
async updateForkProvenance(sessionId, provenance) {
const s = sessions.get(sessionId);
if (s) Object.assign(s, provenance);
diff --git a/src/sessions/postgres-session-store.ts b/src/sessions/postgres-session-store.ts
index 879032f3f..e28b94ffc 100644
--- a/src/sessions/postgres-session-store.ts
+++ b/src/sessions/postgres-session-store.ts
@@ -68,6 +68,7 @@ export function rowToSession(r: Record<string, unknown>): Session {
threadRef: r.thread_ref as string,
...(r.surface != null ? { surface: r.surface as string } : {}),
createdAt: Number(r.created_at),
+ ...(r.status != null ? { status: r.status as Session["status"] } : {}),
...(r.title != null ? { title: r.title as string } : {}),
...(r.channel_name != null ? { channelName: r.channel_name as string } : {}),
...(r.forked_from_session_id != null && r.fork_boundary_seq != null
@@ -566,6 +567,10 @@ export function createPostgresSessionStore(connectionString: string, opts: Store
ON sessions(parent_session_id) WHERE parent_session_id IS NOT NULL`,
],
},
+ {
+ id: "sessions/store/0016-status",
+ statements: ["ALTER TABLE sessions ADD COLUMN IF NOT EXISTS status JSONB"],
+ },
],
[
{
@@ -705,6 +710,13 @@ export function createPostgresSessionStore(connectionString: string, opts: Store
await q("UPDATE sessions SET title = $2 WHERE id = $1", [sessionId, title]);
},
+ async updateStatus(sessionId, status): Promise<void> {
+ await q("UPDATE sessions SET status = $2::jsonb WHERE id = $1", [
+ sessionId,
+ status ? JSON.stringify(status) : null,
+ ]);
+ },
+
async updateForkProvenance(sessionId, provenance): Promise<void> {
await q(
"UPDATE sessions SET forked_from_session_id = $2, forked_from_title = $3, fork_boundary_seq = $4 WHERE id = $1",
diff --git a/src/sessions/session-status.ts b/src/sessions/session-status.ts
new file mode 100644
index 000000000..0d21486b2
--- /dev/null
+++ b/src/sessions/session-status.ts
@@ -0,0 +1,18 @@
+import type { SessionStatus } from "../types.ts";
+
+const emojiPattern = new RegExp("^\\p{RGI_Emoji}$", "v");
+
+export function isSessionStatus(value: unknown): value is SessionStatus | null {
+ if (value === null) return true;
+ if (typeof value !== "object" || Array.isArray(value)) return false;
+ const status = value as Partial<SessionStatus>;
+ return (
+ typeof status.emoji === "string" &&
+ emojiPattern.test(status.emoji) &&
+ typeof status.text === "string" &&
+ status.text.isWellFormed() &&
+ status.text.trim().length > 0 &&
+ status.text.length <= 200 &&
+ !/[\u0000-\u001f\u007f]/u.test(status.text)
+ );
+}
diff --git a/src/sessions/session-store.ts b/src/sessions/session-store.ts
index 204f0e462..8878d8393 100644
--- a/src/sessions/session-store.ts
+++ b/src/sessions/session-store.ts
@@ -699,6 +699,7 @@ export interface SessionStore {
setParentSession(sessionId: string, parentSessionId: string | null): Promise<void>;
setSpawnMeta(sessionId: string, meta: SpawnMeta): Promise<void>;
childrenOf(parentSessionId: string): Promise<Session[]>;
+ updateStatus(sessionId: string, status: Session["status"]): Promise<void>;
updateForkProvenance(
sessionId: string,
provenance: { forkedFrom: { sessionId: string; title?: string | null }; forkBoundarySeq: number },
diff --git a/src/types.ts b/src/types.ts
index af27da0a0..8b5e42b90 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -86,6 +86,11 @@ export interface SpawnMeta {
thinkingLevel?: string;
}
+export interface SessionStatus {
+ emoji: string;
+ text: string;
+}
+
export interface Session {
id: string;
type: SessionType;
@@ -98,6 +103,7 @@ export interface Session {
archived?: boolean;
pinned?: boolean;
color?: string;
+ status?: SessionStatus | null;
forkedFrom?: { sessionId: string; title?: string | null };
forkBoundarySeq?: number;
parentSessionId?: string;
diff --git a/test/agent-conversations-route.test.ts b/test/agent-conversations-route.test.ts
index 1994af519..ac168286a 100644
--- a/test/agent-conversations-route.test.ts
+++ b/test/agent-conversations-route.test.ts
@@ -5,7 +5,7 @@ import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
import { buildApp, type BuiltApp } from "../src/wiring.ts";
import { createServer } from "../src/api/server.ts";
-import { scopeId, type TurnRequest } from "../src/types.ts";
+import { scopeId, type TurnRequest, type SessionStatus } from "../src/types.ts";
import { mintCapabilityToken, CAPABILITY_TTL_MS, CONTROL_PLANE_AUD } from "../src/auth/capability-token.ts";
import { testConfig } from "./support/test-config.ts";
@@ -67,6 +67,47 @@ describe("agent conversations self-API", async () => {
await new Promise<void>((resolve) => server.close(() => resolve()));
});
+ it("sets, replaces, lists and clears a shared session status", async () => {
+ const token = await capFor("U1");
+ await built.sessions.addParticipant(mineId, "U3");
+ for (const status of [{ emoji: "βœ…", text: "PR merged" }, { emoji: "πŸš€", text: "Live in production" }, null]) {
+ const res = await post(`/v1/conversations/${mineId}`, { status }, token);
+ assert.equal(res.status, 200);
+ assert.deepEqual(
+ ((await res.json()) as { conversation: { status: SessionStatus | null } }).conversation.status,
+ status,
+ );
+ assert.deepEqual((await built.app.getSessionForViewer(mineId, "U3"))?.session.status ?? null, status);
+ const list = await get("/v1/conversations", token);
+ assert.deepEqual(
+ (
+ (await list.json()) as { conversations: Array<{ id: string; status: SessionStatus | null }> }
+ ).conversations.find((s) => s.id === mineId)?.status,
+ status,
+ );
+ }
+ });
+
+ it("rejects malformed status and unauthorized status updates", async () => {
+ const token = await capFor("U1");
+ for (const status of [
+ {},
+ { emoji: "abc", text: "Merged" },
+ { emoji: "βœ…πŸš€", text: "Merged" },
+ { emoji: "βœ…", text: " " },
+ { emoji: "βœ…", text: "x".repeat(201) },
+ { emoji: "βœ…", text: "a\u0000b" },
+ "merged",
+ ]) {
+ assert.equal((await post(`/v1/conversations/${mineId}`, { status }, token)).status, 400);
+ }
+ assert.equal(
+ (await post(`/v1/conversations/${theirsId}`, { status: { emoji: "βœ…", text: "Merged" } }, token)).status,
+ 404,
+ );
+ assert.equal((await post(`/v1/conversations/${mineId}`, { status: null })).status, 401);
+ });
+
it("spawns a fresh conversation with only the seed text", async () => {
const token = await capFor("U1");
const res = await post(
diff --git a/test/postgres-store.test.ts b/test/postgres-store.test.ts
index 2d1a7e685..532d2686a 100644
--- a/test/postgres-store.test.ts
+++ b/test/postgres-store.test.ts
@@ -2553,3 +2553,17 @@ test("pg personal conversation counts tolerate legacy null characters", { skip }
await raw.end();
}
});
+
+test("pg session status survives restart, is shared, and clears", { skip }, async () => {
+ const first = createPostgresSessionStore(URL!);
+ const session = await first.getOrCreateByThread("session-status", "dm", scopeId("personal", "U1"));
+ await first.addParticipant(session.id, "U1");
+ await first.addParticipant(session.id, "U2");
+ const status = { emoji: "πŸš€", text: "Live in production" };
+ await first.updateStatus(session.id, status);
+ const restarted = createPostgresSessionStore(URL!);
+ assert.deepEqual((await restarted.get(session.id))?.status, status);
+ assert.deepEqual((await restarted.getForParticipant(session.id, "U2"))?.status, status);
+ await restarted.updateStatus(session.id, null);
+ assert.equal((await first.get(session.id))?.status ?? null, null);
+});
diff --git a/test/session-status.test.ts b/test/session-status.test.ts
new file mode 100644
index 000000000..02aefd55d
--- /dev/null
+++ b/test/session-status.test.ts
@@ -0,0 +1,39 @@
+import "./support/auto-fake-sprites.ts";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { isSessionStatus } from "../src/sessions/session-status.ts";
+import { buildApp } from "../src/wiring.ts";
+import { testConfig } from "./support/test-config.ts";
+import type { SessionStateEvent } from "../src/runs/session-state-bus.ts";
+
+test("status accepts compound emoji and rejects multiple emoji, shortcodes, and empty text", () => {
+ for (const emoji of ["βœ…", "πŸš€", "πŸ‘©πŸ½β€πŸ’»", "πŸ‡ΊπŸ‡Έ", "1️⃣"]) assert.ok(isSessionStatus({ emoji, text: "Ready" }));
+ for (const emoji of ["", "a", ":rocket:", "πŸš€βœ…"]) assert.equal(isSessionStatus({ emoji, text: "Ready" }), false);
+ for (const text of ["Ready\ud800", "Ready\udc00"]) assert.equal(isSessionStatus({ emoji: "βœ…", text }), false);
+ assert.equal(isSessionStatus(undefined), false);
+ assert.ok(isSessionStatus(null));
+});
+
+test("status changes notify viewers without changing run state; former participants cannot write", async () => {
+ const built = buildApp(testConfig({}));
+ const turn = await built.app.turn({
+ surface: "test",
+ actor: { externalId: "U1" },
+ conversation: { kind: "dm", threadRef: "status-notify" },
+ text: "hello",
+ });
+ const id = turn.sessionId!;
+ await built.sessions.addParticipant(id, "U2");
+ const events: SessionStateEvent[] = [];
+ const unsub = built.app.subscribeSessionStates((e) => events.push(e));
+ const status = { emoji: "βœ…", text: "PR merged" };
+ assert.deepEqual((await built.app.updateSession(id, "U1", { status }))?.status, status);
+ await new Promise((resolve) => setImmediate(resolve));
+ assert.equal(events.length, 1);
+ assert.equal(events[0]?.state, "metadata");
+ assert.ok(events[0]?.participants?.includes("U2"));
+ await built.sessions.removeParticipant(id, "U2");
+ assert.equal(await built.app.updateSession(id, "U2", { status: null }), null);
+ assert.deepEqual((await built.sessions.get(id))?.status, status);
+ unsub();
+});
diff --git a/test/session-view-patch.test.ts b/test/session-view-patch.test.ts
index 643b0f908..49d3ef76c 100644
--- a/test/session-view-patch.test.ts
+++ b/test/session-view-patch.test.ts
@@ -93,3 +93,20 @@ test("POST /v1/sessions/:id rejects malformed colors and non-boolean pins", asyn
await srv.close();
}
});
+
+test("surface session route sets and clears status, rejecting malformed input", async () => {
+ const srv = start();
+ try {
+ const id = await newSession(srv.base, "web:U1:status");
+ const status = { emoji: "πŸš€", text: "Live in production" };
+ const set = await patch(srv.base, id, { principalId: "U1", status });
+ assert.equal(set.status, 200);
+ assert.deepEqual(set.session?.status, status);
+ assert.equal((await patch(srv.base, id, { principalId: "U1", status: {} })).status, 400);
+ const cleared = await patch(srv.base, id, { principalId: "U1", status: null });
+ assert.equal(cleared.status, 200);
+ assert.equal(cleared.session?.status ?? null, null);
+ } finally {
+ await srv.close();
+ }
+});