@heyramzi/tasks 0.0.0-stage → 0.4.0

package/src/inbox/inbox-card.svelte

@@ -0,0 +1,279 @@
+<script lang="ts">
+	import { untrack, type Snippet } from "svelte";
+	import { AgentAvatar } from "@heyramzi/ui/agents";
+	import { PixelLoader } from "@heyramzi/ui/ai/loading-state";
+	import { Button } from "@heyramzi/ui/shadcn/button";
+	import { Textarea } from "@heyramzi/ui/shadcn/textarea";
+	import { cn } from "../lib/cn.js";
+	import StatusBadge from "../status-badge.svelte";
+	import StatusDot from "../status-dot.svelte";
+	import { TONE_TEXT } from "../tone.js";
+	import InboxDraftEditor from "./inbox-draft.svelte";
+	import { canUndo, isOpen, startDraft } from "./inbox-logic.js";
+	import {
+		SOURCE_ICON,
+		SOURCE_LABEL,
+		confidenceLevel,
+		inboxConfidence,
+		inboxKinds,
+		inboxStates,
+	} from "./inbox-statuses.js";
+	import InboxTraceView from "./inbox-trace.svelte";
+	import type { InboxDraftEdits, InboxItem, InboxVerdict } from "./inbox-types.js";
+
+	type Props = {
+		item: InboxItem;
+		/** The keyboard cursor is on this card. */
+		selected?: boolean;
+		onselect?: () => void;
+		onverdict: (verdict: InboxVerdict) => void;
+		/** Replaces the summary lines, for a host that renders its own proposal. */
+		renderProposal?: Snippet<[InboxItem]>;
+	};
+
+	let { item, selected = false, onselect, onverdict, renderProposal }: Props = $props();
+
+	let drafts = $derived(item.proposal.drafts ?? []);
+	let open = $derived(isOpen(item));
+	let level = $derived(confidenceLevel(item.confidence.score));
+	let tone = $derived(inboxConfidence.tone(level));
+
+	let pickedDraft = $state<string>();
+	let edits = $state<InboxDraftEdits>({});
+	let bodyEl = $state<HTMLTextAreaElement | null>(null);
+	let steering = $state(false);
+	let note = $state("");
+	let noteEl = $state<HTMLTextAreaElement | null>(null);
+	let copied = $state(false);
+
+	// WHY the selection is derived from the pick: a revised proposal brings new
+	// drafts, and the old pick may not exist in them. The agent's choice wins then.
+	let selectedDraft = $derived(
+		drafts.find((d) => d.templateId === pickedDraft) ??
+			startDraft(drafts, item.proposal.recommended),
+	);
+
+	// WHY: when the agent hands back a new set of drafts, the person's old edits
+	// belong to text that no longer exists.
+	let seenDrafts = untrack(() => item.proposal.drafts);
+	$effect.pre(() => {
+		if (item.proposal.drafts === seenDrafts) return;
+		seenDrafts = item.proposal.drafts;
+		edits = {};
+		pickedDraft = undefined;
+	});
+
+	function current() {
+		if (!selectedDraft) return undefined;
+		const text = edits[selectedDraft.templateId] ?? selectedDraft;
+		return { templateId: selectedDraft.templateId, subject: text.subject, body: text.body };
+	}
+
+	export function approve() {
+		if (!open) return;
+		// Sending the decline template closes the item as declined, whichever button sent it.
+		const type = selectedDraft?.outcome === "decline" ? "decline" : "approve";
+		onverdict({ type, id: item.id, draft: current() });
+	}
+
+	export function decline() {
+		if (!open) return;
+		const template = drafts.find((d) => d.outcome === "decline");
+		// With a decline template, the shortcut loads it for editing. Sending stays an explicit Send.
+		if (template) {
+			pickedDraft = template.templateId;
+			edit();
+			return;
+		}
+		onverdict({ type: "decline", id: item.id });
+	}
+
+	export function steer() {
+		if (!open) return;
+		steering = true;
+		queueMicrotask(() => noteEl?.focus());
+	}
+
+	export function edit() {
+		if (!open || !drafts.length) return;
+		queueMicrotask(() => bodyEl?.focus());
+	}
+
+	export function undo() {
+		if (canUndo(item)) onverdict({ type: "undo", id: item.id });
+	}
+
+	function submitSteer() {
+		const text = note.trim();
+		if (!text) return;
+		onverdict({ type: "steer", id: item.id, note: text });
+		steering = false;
+		note = "";
+	}
+
+	function onNoteKeydown(event: KeyboardEvent) {
+		if (event.key === "Escape") {
+			steering = false;
+			event.stopPropagation();
+		} else if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+			event.preventDefault();
+			submitSteer();
+		}
+	}
+
+	async function copy() {
+		const draft = current();
+		if (!draft) return;
+		try {
+			await navigator.clipboard.writeText(`${draft.subject}\n\n${draft.body}`);
+			copied = true;
+			setTimeout(() => (copied = false), 1600);
+		} catch {
+			copied = false;
+		}
+	}
+
+	let sendLabel = $derived(
+		drafts.length > 1 && selectedDraft
+			? `Send ${selectedDraft.label.toLowerCase()}`
+			: drafts.length
+				? "Approve and send"
+				: "Approve",
+	);
+</script>
+
+<!-- WHY a bordered card only while it waits: a decided or automatic item is a
+     line in a log, so it loses the border and the queue stays scannable. -->
+<!-- WHY a focusable article: j and k move focus card to card, and a screen reader
+     reads the card as one labelled unit. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<article
+	data-inbox-item={item.id}
+	data-selected={selected || undefined}
+	aria-label={item.title}
+	tabindex={selected ? 0 : -1}
+	onfocusin={onselect}
+	onpointerdown={onselect}
+	class={cn(
+		"flex flex-col gap-3 rounded-xl p-3 outline-none transition-[background-color,border-color,box-shadow] duration-[var(--duration-quick,120ms)] ease-[var(--ease-smooth-out,ease-out)]",
+		"focus-visible:ring-ring/50 focus-visible:ring-3",
+		open ? "border-border bg-card border shadow-[var(--elev-card,none)]" : "bg-muted/30 border border-transparent",
+		selected && open && "border-ring",
+	)}
+>
+	<header class="flex items-start gap-2.5">
+		<StatusDot statuses={inboxStates} status={item.state} class="mt-0.5" />
+		<span class="sr-only">{inboxStates.label(item.state)}.</span>
+		<div class="flex min-w-0 flex-1 flex-col gap-1">
+			<div class="flex flex-wrap items-center gap-x-2 gap-y-1">
+				<h3 class="text-sm leading-5 font-medium text-balance">{item.title}</h3>
+				<StatusBadge statuses={inboxKinds} status={item.kind} />
+				{#if !open}
+					<StatusBadge statuses={inboxStates} status={item.state} />
+				{/if}
+			</div>
+			{#if renderProposal}
+				{@render renderProposal(item)}
+			{:else}
+				<p class="text-muted-foreground text-sm text-pretty">{item.proposal.summary}</p>
+				{#if item.proposal.detail}
+					<p class="text-muted-foreground text-sm text-pretty">{item.proposal.detail}</p>
+				{/if}
+			{/if}
+		</div>
+	</header>
+
+	<div class="text-muted-foreground flex flex-wrap items-center gap-x-4 gap-y-1 pl-6 text-xs">
+		<span class="inline-flex items-center gap-1.5">
+			<span class="size-3.5 [&>svg]:size-full" aria-hidden="true">{@html SOURCE_ICON[item.trace.source.type]}</span>
+			{SOURCE_LABEL[item.trace.source.type]}, {item.trace.source.at}
+		</span>
+		<span class={cn("inline-flex items-center gap-1.5 tabular-nums", TONE_TEXT[tone])}>
+			<StatusDot
+				statuses={inboxConfidence}
+				status={level}
+				progress={item.confidence.score}
+				size={12}
+				animate={false}
+			/>
+			{Math.round(item.confidence.score * 100)}% sure
+		</span>
+		{#if item.agent}
+			<span class="inline-flex items-center gap-1.5">
+				<AgentAvatar
+					name={item.agent.name}
+					shape={item.agent.shape}
+					color={item.agent.color}
+					state={item.state === "working" ? "working" : "default"}
+					size={16}
+				/>
+				{item.agent.name}
+			</span>
+		{/if}
+	</div>
+
+	{#if item.confidence.missing && level !== "high" && open}
+		<p class={cn("pl-6 text-sm", TONE_TEXT[tone])}>Missing: {item.confidence.missing}</p>
+	{/if}
+
+	<div class="pl-6">
+		<InboxTraceView trace={item.trace} />
+	</div>
+
+	{#if item.state === "working"}
+		<div class="flex flex-col gap-1.5 pl-6">
+			<PixelLoader label="Agent is re-running with your note" />
+			{#if item.steer}
+				<p class="text-muted-foreground border-border border-l-2 pl-3 text-sm">&ldquo;{item.steer}&rdquo;</p>
+			{/if}
+		</div>
+	{/if}
+
+	{#if open && drafts.length && selectedDraft}
+		<div class="pl-6">
+			<InboxDraftEditor
+				{drafts}
+				recommended={item.proposal.recommended}
+				selected={selectedDraft.templateId}
+				bind:edits
+				bind:bodyEl
+				onpick={(id) => (pickedDraft = id)}
+			/>
+		</div>
+	{/if}
+
+	{#if open && steering}
+		<div class="flex flex-col gap-2 pl-6">
+			<Textarea
+				bind:ref={noteEl}
+				bind:value={note}
+				onkeydown={onNoteKeydown}
+				placeholder="Tell the agent what to do instead"
+				aria-label="Note for the agent"
+				class="bg-background min-h-20 text-sm"
+			/>
+			<div class="flex flex-wrap items-center gap-2">
+				<Button size="sm" onclick={submitSteer} disabled={!note.trim()}>Send to agent</Button>
+				<Button size="sm" variant="ghost" onclick={() => (steering = false)}>Cancel</Button>
+				<span class="text-muted-foreground text-xs max-sm:hidden">The agent retries with your note.</span>
+			</div>
+		</div>
+	{:else if open}
+		<div class="flex flex-wrap items-center gap-2 pl-6">
+			<Button size="sm" onclick={approve} aria-keyshortcuts="a">{sendLabel}</Button>
+			{#if !drafts.some((d) => d.outcome === "decline")}
+				<Button size="sm" variant="destructive" onclick={decline} aria-keyshortcuts="d">Decline</Button>
+			{/if}
+			<Button size="sm" variant="outline" onclick={steer} aria-keyshortcuts="s">Steer</Button>
+			{#if drafts.length}
+				<Button size="sm" variant="ghost" onclick={copy} class="ml-auto" aria-live="polite">
+					{copied ? "Copied" : "Copy"}
+				</Button>
+			{/if}
+		</div>
+	{:else if canUndo(item)}
+		<div class="pl-6">
+			<Button size="sm" variant="outline" onclick={undo} aria-keyshortcuts="u">Undo</Button>
+		</div>
+	{/if}
+</article>

package/src/inbox/inbox-draft.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+	import { Input } from "@heyramzi/ui/shadcn/input";
+	import { Textarea } from "@heyramzi/ui/shadcn/textarea";
+	import { ToggleGroup, ToggleGroupItem } from "@heyramzi/ui/shadcn/toggle-group";
+	import { cn } from "../lib/cn.js";
+	import { insetWellClass } from "../tone.js";
+	import type { InboxDraft, InboxDraftEdits } from "./inbox-types.js";
+
+	type Props = {
+		drafts: InboxDraft[];
+		/** The template the agent picked. Marked in the picker. */
+		recommended?: string;
+		selected: string;
+		/** What the person typed, by template. A template with no entry shows the agent's text. */
+		edits: InboxDraftEdits;
+		/** The person picked another template. */
+		onpick: (templateId: string) => void;
+		/** The body field, so a shortcut can focus it. */
+		bodyEl?: HTMLTextAreaElement | null;
+		disabled?: boolean;
+		class?: string;
+	};
+
+	let {
+		drafts,
+		recommended,
+		selected,
+		onpick,
+		edits = $bindable(),
+		bodyEl = $bindable(null),
+		disabled = false,
+		class: className,
+	}: Props = $props();
+
+	let draft = $derived(drafts.find((d) => d.templateId === selected) ?? drafts[0]);
+	let text = $derived(edits[draft.templateId] ?? { subject: draft.subject, body: draft.body });
+	let edited = $derived(text.subject !== draft.subject || text.body !== draft.body);
+
+	function write(patch: Partial<{ subject: string; body: string }>) {
+		edits[draft.templateId] = { ...text, ...patch };
+	}
+</script>
+
+<div class={cn(insetWellClass, "flex flex-col gap-2", className)}>
+	{#if drafts.length > 1}
+		<ToggleGroup
+			type="single"
+			variant="outline"
+			size="sm"
+			value={selected}
+			onValueChange={(next) => next && onpick(next)}
+			aria-label="Reply template"
+			class="flex-wrap"
+		>
+			{#each drafts as d (d.templateId)}
+				<ToggleGroupItem value={d.templateId} {disabled}>
+					{d.label}
+					{#if d.templateId === recommended}
+						<span class="text-muted-foreground text-xs font-normal">suggested</span>
+					{/if}
+				</ToggleGroupItem>
+			{/each}
+		</ToggleGroup>
+	{/if}
+
+	<Input
+		value={text.subject}
+		oninput={(event) => write({ subject: event.currentTarget.value })}
+		aria-label="Subject"
+		{disabled}
+		class="bg-background"
+	/>
+	<Textarea
+		bind:ref={bodyEl}
+		value={text.body}
+		oninput={(event) => write({ body: event.currentTarget.value })}
+		aria-label="Email body"
+		{disabled}
+		class="bg-background min-h-28 text-sm"
+	/>
+	<p class="text-muted-foreground text-xs" aria-live="polite">
+		{edited ? "Edited by you. Send uses your text." : "The agent's draft. Edit it before you send."}
+	</p>
+</div>

package/src/inbox/inbox-logic.ts

@@ -0,0 +1,56 @@
+import type {
+	InboxDraft,
+	InboxItem,
+	InboxKindFilter,
+	InboxLane,
+	InboxProject,
+	InboxVerdict,
+} from "./inbox-types.js";
+
+/** Which lane an item sits in. The agent's own work and the person's decisions never share one. */
+export function laneOf(item: InboxItem): InboxLane {
+	if (item.tier === "auto") return "auto";
+	return item.state === "proposed" || item.state === "working" ? "needs" : "decided";
+}
+
+export function inLane(items: InboxItem[], lane: InboxLane, kind: InboxKindFilter): InboxItem[] {
+	return items.filter((item) => laneOf(item) === lane && (kind === "all" || item.kind === kind));
+}
+
+export type InboxGroup = { project: InboxProject; items: InboxItem[] };
+
+/** Group by project in order of first appearance, so the oldest waiting item keeps its place. */
+export function groupByProject(items: InboxItem[]): InboxGroup[] {
+	const groups = new Map<string, InboxGroup>();
+	for (const item of items) {
+		const group = groups.get(item.project.id);
+		if (group) group.items.push(item);
+		else groups.set(item.project.id, { project: item.project, items: [item] });
+	}
+	return [...groups.values()];
+}
+
+/** Items in the order the screen shows them, so j and k walk what the eye sees. */
+export function flatten(groups: InboxGroup[]): InboxItem[] {
+	return groups.flatMap((group) => group.items);
+}
+
+/** The draft to open on: the agent's pick, else the first. */
+export function startDraft(drafts: InboxDraft[], recommended?: string): InboxDraft | undefined {
+	return drafts.find((draft) => draft.templateId === recommended) ?? drafts[0];
+}
+
+/** A person can act on an item only while it waits for them. */
+export function isOpen(item: InboxItem): boolean {
+	return item.tier === "ask" && item.state === "proposed";
+}
+
+export function canUndo(item: InboxItem): boolean {
+	return item.tier === "auto" && item.state === "done";
+}
+
+/** True when a key press belongs to a text field and so isn't a shortcut. */
+export function isTyping(target: EventTarget | null): boolean {
+	if (!(target instanceof HTMLElement)) return false;
+	return target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName);
+}

package/src/inbox/inbox-statuses.ts

@@ -0,0 +1,50 @@
+import { defineStatuses } from "../define-statuses.js";
+import callIcon from "./icons/call.svg?raw";
+import emailIcon from "./icons/email.svg?raw";
+import formIcon from "./icons/form.svg?raw";
+import slackIcon from "./icons/slack.svg?raw";
+import type { InboxSourceType } from "./inbox-types.js";
+
+/** The lifecycle of an item. The dot and the badge both read this one map. */
+export const inboxStates = defineStatuses({
+	proposed: { label: "Needs you", tone: "warning", variant: "open" },
+	working: { label: "Agent working", tone: "accent", variant: "progress", progress: 0.6 },
+	approved: { label: "Approved", tone: "success", variant: "completed" },
+	declined: { label: "Declined", tone: "neutral", variant: "lost" },
+	done: { label: "Done by agent", tone: "success", variant: "completed" },
+	undone: { label: "Undone", tone: "neutral", variant: "lost" },
+});
+
+/** What the agent made of the touchpoint. */
+export const inboxKinds = defineStatuses({
+	information: { label: "Information", tone: "info", variant: "filled" },
+	action: { label: "Action", tone: "accent", variant: "filled" },
+	decision: { label: "Decision", tone: "warning", variant: "filled" },
+});
+
+/** How sure the agent is, bucketed. The dot's fill carries the exact score. */
+export const inboxConfidence = defineStatuses({
+	high: { label: "Confident", tone: "success", variant: "progress" },
+	medium: { label: "Unsure", tone: "warning", variant: "progress" },
+	low: { label: "Guessing", tone: "destructive", variant: "progress" },
+});
+
+export function confidenceLevel(score: number): "high" | "medium" | "low" {
+	if (score >= 0.8) return "high";
+	if (score >= 0.5) return "medium";
+	return "low";
+}
+
+export const SOURCE_ICON: Record<InboxSourceType, string> = {
+	call: callIcon,
+	email: emailIcon,
+	slack: slackIcon,
+	form: formIcon,
+};
+
+export const SOURCE_LABEL: Record<InboxSourceType, string> = {
+	call: "Call",
+	email: "Email",
+	slack: "Slack",
+	form: "Form",
+};

package/src/inbox/inbox-trace.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import { Reasoning, ReasoningContent, ReasoningTrigger } from "@heyramzi/ui/ai/reasoning";
+	import { SOURCE_ICON, SOURCE_LABEL } from "./inbox-statuses.js";
+	import type { InboxTrace } from "./inbox-types.js";
+
+	type Props = { trace: InboxTrace };
+
+	let { trace }: Props = $props();
+
+	let count = $derived(trace.evidence.length);
+</script>
+
+<!-- WHY the shared Reasoning and not a local disclosure: it is already the
+     collapsed-by-default "how the agent got here" pattern, with the same chevron. -->
+<Reasoning>
+	<ReasoningTrigger class="w-auto">
+		<span class="size-3.5 shrink-0 [&>svg]:size-full" aria-hidden="true">{@html SOURCE_ICON[trace.source.type]}</span>
+		<span>
+			Trace: {SOURCE_LABEL[trace.source.type]}, {trace.source.at}, {count}
+			{count === 1 ? "quote" : "quotes"}
+		</span>
+	</ReasoningTrigger>
+	<ReasoningContent>
+		<div class="flex flex-col gap-3">
+			<p class="text-foreground">
+				{trace.source.label}
+				{#if trace.source.href}
+					<a href={trace.source.href} class="text-foreground ml-1 underline underline-offset-2">Open source</a>
+				{/if}
+			</p>
+			<ul class="flex flex-col gap-2">
+				{#each trace.evidence as evidence, i (i)}
+					<li>
+						<blockquote class="text-foreground">&ldquo;{evidence.quote}&rdquo;</blockquote>
+						{#if evidence.by || evidence.at}
+							<span class="text-xs tabular-nums">{[evidence.by, evidence.at].filter(Boolean).join(", ")}</span>
+						{/if}
+					</li>
+				{/each}
+			</ul>
+			<p><span class="text-foreground font-medium">Why:</span> {trace.reasoning}</p>
+		</div>
+	</ReasoningContent>
+</Reasoning>

package/src/inbox/inbox-types.ts

@@ -0,0 +1,108 @@
+import type { AgentShape } from "@heyramzi/ui/agents";
+
+/** What the agent decided the touchpoint is: a fact to file, a task to do, or a call only a person makes. */
+export type InboxKind = "information" | "action" | "decision";
+
+/** `auto` was already done by the agent and can be undone. `ask` waits for a verdict. */
+export type InboxTier = "auto" | "ask";
+
+export type InboxState = "proposed" | "working" | "approved" | "declined" | "done" | "undone";
+
+export type InboxSourceType = "call" | "email" | "slack" | "form";
+
+/** The three outcomes of a reply draft. Decline is the only one that closes the item without a yes. */
+export type InboxOutcome = "approve" | "decline" | "clarify";
+
+/** An editable email, filled in from a template by the agent. */
+export type InboxDraft = {
+	/** The template it came from. Comes back in the verdict so the host knows which one was sent. */
+	templateId: string;
+	/** The button's word: "Pre-qualify", "Decline", "Clarify". */
+	label: string;
+	subject: string;
+	body: string;
+	outcome?: InboxOutcome;
+};
+
+/** What the agent wants to do, in one line, with the drafts it prepared. */
+export type InboxProposal = {
+	summary: string;
+	detail?: string;
+	drafts?: InboxDraft[];
+	/** The draft to open on. Defaults to the first. */
+	recommended?: string;
+};
+
+/** A short quote the agent read. */
+export type InboxEvidence = {
+	quote: string;
+	/** Who said it, or where it sat: "Priya", "line 14". */
+	by?: string;
+	/** A position in the source, such as "12:41" in a call. */
+	at?: string;
+};
+
+/** Where an item came from and what the agent made of it. Every verdict is traceable to this. */
+export type InboxTrace = {
+	source: {
+		type: InboxSourceType;
+		label: string;
+		/** Display time, formatted by the host so server and browser agree. */
+		at: string;
+		href?: string;
+	};
+	evidence: InboxEvidence[];
+	reasoning: string;
+};
+
+export type InboxConfidence = {
+	/** 0 to 1. */
+	score: number;
+	/** What the agent couldn't tell. Shown when the agent is unsure. */
+	missing?: string;
+};
+
+export type InboxProject = {
+	id: string;
+	name: string;
+	client?: string;
+	/** The project timeline. Decided items link here. */
+	href?: string;
+};
+
+export type InboxAgent = {
+	name: string;
+	shape?: AgentShape;
+	color?: string;
+};
+
+export type InboxItem = {
+	id: string;
+	kind: InboxKind;
+	tier: InboxTier;
+	state: InboxState;
+	title: string;
+	project: InboxProject;
+	proposal: InboxProposal;
+	confidence: InboxConfidence;
+	trace: InboxTrace;
+	agent?: InboxAgent;
+	/** The last steer note, shown while the agent re-runs. */
+	steer?: string;
+};
+
+/** The draft as the person left it, after editing. */
+export type InboxDraftEdit = Pick<InboxDraft, "templateId" | "subject" | "body">;
+
+export type InboxVerdict =
+	| { type: "approve"; id: string; draft?: InboxDraftEdit }
+	| { type: "decline"; id: string; draft?: InboxDraftEdit }
+	| { type: "steer"; id: string; note: string }
+	| { type: "undo"; id: string };
+
+export type InboxLane = "needs" | "auto" | "decided";
+
+export type InboxKindFilter = "all" | InboxKind;
+
+/** What the person typed into the drafts, by template id. */
+export type InboxDraftEdits = Record<string, { subject: string; body: string }>;