zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/web/collaboration.js

@@ -0,0 +1,290 @@
+// Agent collaboration on the web (agent-collaboration-292 task 11, contract C-10). Only decisions live here, with no
+// DOM, so test/unit/agent-collaboration-web.test.ts can exercise them: the per-conversation card state built from the
+// stored `message.collaboration` / `agent.collaboration.*` events and the owner listing, the card view model (who asked
+// whom, kind, state word, result, files, which actions apply), the owner requests (cancel, download, listing) and what
+// their answers mean, the directional targets editor options and the source-file origin labels. app.js draws from these.
+import { formatBytes } from "./gc.js";
+import strings from "./i18n/agents.js";
+import { registerStrings, t } from "./i18n.js";
+
+registerStrings(strings);
+
+export const REQUESTS_PATH = "/api/agent-collaboration/requests";
+export const ARTIFACTS_PATH = "/api/agent-collaboration/artifacts";
+/** The gateway's request states (src/store.ts agent_requests CHECK); anything else is shown as unconfirmed, never as done. */
+export const REQUEST_STATES = Object.freeze(["queued", "running", "waiting_peer", "waiting_owner", "result_preparing", "completed", "failed", "interrupted", "cancel_requested", "cancelled", "unresolved_delivery", "version_conflict"]);
+/** A request in one of these states never changes again; everything else may still move, including cancel_requested. */
+export const TERMINAL_STATES = Object.freeze(["completed", "failed", "interrupted", "cancelled", "version_conflict"]);
+const UNCERTAIN_STATES = Object.freeze(["unresolved_delivery", "cancel_requested", "version_conflict"]);
+const KINDS = Object.freeze(["task", "question"]);
+
+const isText = (value) => typeof value === "string";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+export function isTerminal(state) {
+	return TERMINAL_STATES.includes(state);
+}
+
+/** The cards of one conversation: a new empty state (one per shown conversation). */
+export function emptyCards() {
+	return new Map();
+}
+
+function blank(requestId) {
+	return { requestId, rootId: null, kind: null, text: null, files: [], actor: null, targetAgent: null, outgoing: null, seq: null, ts: null,
+		state: null, revision: null, resultId: null, result: null, replied: false, blocked: null, deliveryUnknown: false, listed: false };
+}
+
+function manifestRows(manifest) {
+	if (!Array.isArray(manifest)) return [];
+	return manifest.filter((row) => record(row) && isText(row.id)).map((row) => ({
+		artifactId: row.id, name: isText(row.originalName) && row.originalName ? row.originalName : row.id,
+		bytes: typeof row.bytes === "number" ? row.bytes : null, sha256: isText(row.sha256) ? row.sha256 : null, mediaType: isText(row.mediaType) ? row.mediaType : null,
+	}));
+}
+
+/**
+ * One stored or live event folded into the cards. Returns the next map (the given one is not changed), the request the
+ * event touched, and what happened to its card: "created" (its first appearance, drawn at this event), "updated" (an
+ * existing card changed) or null (nothing to draw: an identical replay, or an event without a request). A notice is an
+ * event that names no request (blocked input, waiting for the owner's answer) and is shown as one system line.
+ */
+export function applyCollaborationEvent(cards, event) {
+	const next = new Map(cards);
+	const data = record(event?.data) ? event.data : {};
+	const requestId = isText(data.requestId) ? data.requestId : null;
+	const seq = typeof event?.seq === "number" ? event.seq : null;
+	const ts = isText(event?.ts) ? event.ts : null;
+	const none = { cards, requestId: null, change: null, notice: null };
+	switch (event?.type) {
+		case "message.collaboration": {
+			if (!requestId || (data.direction !== "request" && data.direction !== "reply")) return none;
+			const prior = next.get(requestId) ?? blank(requestId);
+			let card = { ...prior };
+			if (data.direction === "request") {
+				if (prior.text !== null && prior.seq !== null) return none;
+				card = { ...card, text: isText(data.text) ? data.text : "", files: Array.isArray(data.files) ? data.files.filter(isText) : [],
+					actor: record(data.actor) ? { kind: data.actor.kind === "main" ? "main" : "agent", id: isText(data.actor.id) ? data.actor.id : null } : card.actor,
+					outgoing: data.outgoing === true, rootId: isText(data.rootId) ? data.rootId : card.rootId };
+			} else {
+				const resultId = isText(data.resultId) ? data.resultId : null;
+				if (data.outgoing === true) {
+					if (prior.replied) return none;
+					card = { ...card, replied: true, resultId: resultId ?? card.resultId, outgoing: prior.outgoing ?? false };
+				} else {
+					if (prior.result && prior.result.resultId === resultId) return none;
+					card = { ...card, resultId: resultId ?? card.resultId, outgoing: prior.outgoing ?? true, rootId: isText(data.rootId) ? data.rootId : card.rootId,
+						result: { resultId, text: isText(data.text) ? data.text : "", files: manifestRows(data.manifest) } };
+				}
+			}
+			const created = prior.seq === null;
+			if (created) card = { ...card, seq, ts };
+			next.set(requestId, card);
+			return { cards: next, requestId, change: created ? "created" : "updated", notice: null };
+		}
+		case "agent.collaboration.status": {
+			if (!requestId || !isText(data.state)) return none;
+			const prior = next.get(requestId) ?? blank(requestId);
+			const revision = typeof data.revision === "number" ? data.revision : null;
+			if (prior.revision !== null && revision !== null && revision <= prior.revision) return none;
+			if (prior.state === data.state && prior.revision === revision) return none;
+			next.set(requestId, { ...prior, state: data.state, revision: revision ?? prior.revision });
+			return { cards: next, requestId, change: prior.seq === null ? null : "updated", notice: null };
+		}
+		case "agent.collaboration.blocked": {
+			const code = isText(data.code) ? data.code : "unknown";
+			if (!requestId) return { cards, requestId: null, change: null, notice: t("collab.notice.blocked", { code }) };
+			const prior = next.get(requestId) ?? blank(requestId);
+			if (prior.blocked === code) return none;
+			next.set(requestId, { ...prior, blocked: code });
+			return { cards: next, requestId, change: prior.seq === null ? null : "updated", notice: null };
+		}
+		case "agent.collaboration.waiting_owner":
+			return { cards, requestId: null, change: null, notice: t("collab.notice.waitingOwner") };
+		case "agent.collaboration.delivery_unknown": {
+			if (!requestId) return { cards, requestId: null, change: null, notice: t("collab.notice.deliveryUnknown") };
+			const prior = next.get(requestId) ?? blank(requestId);
+			if (prior.deliveryUnknown) return none;
+			next.set(requestId, { ...prior, deliveryUnknown: true });
+			return { cards: next, requestId, change: prior.seq === null ? null : "updated", notice: null };
+		}
+		default:
+			return none;
+	}
+}
+
+/**
+ * The gateway's C-4 fallback `notice {kind:"collaboration",requestId,direction}` repeats a collaboration message for apps
+ * that do not know it. The web draws that message as its card, so it never draws the same request/direction notice too.
+ */
+export function isCollaborationFallback(event) {
+	const data = record(event?.data) ? event.data : {};
+	return event?.type === "notice" && data.kind === "collaboration" && isText(data.requestId) && (data.direction === "request" || data.direction === "reply");
+}
+
+/**
+ * The owner listing (GET /api/agent-collaboration/requests?conv=) is the gateway's current truth for kind, state,
+ * revision and target agent of every request this conversation asked or received; the stored events alone leave the
+ * receiving side without state changes and a sent card without its recipient. Returns the next map and the ids of the
+ * drawn cards whose view changed.
+ */
+export function mergeRequestListing(cards, listing) {
+	const rows = Array.isArray(listing?.requests) ? listing.requests : [];
+	const next = new Map(cards);
+	const changed = [];
+	for (const row of rows) {
+		if (!record(row) || !isText(row.requestId)) continue;
+		const prior = next.get(row.requestId) ?? blank(row.requestId);
+		const card = { ...prior, listed: true,
+			kind: KINDS.includes(row.kind) ? row.kind : prior.kind,
+			state: isText(row.state) ? row.state : prior.state,
+			revision: typeof row.revision === "number" ? row.revision : prior.revision,
+			resultId: isText(row.resultId) ? row.resultId : prior.resultId,
+			rootId: isText(row.rootId) ? row.rootId : prior.rootId,
+			targetAgent: isText(row.targetAgent) && row.targetAgent ? row.targetAgent : prior.targetAgent,
+			text: prior.text ?? (isText(row.text) ? row.text : null),
+			files: prior.files.length ? prior.files : Array.isArray(row.files) ? row.files.filter(isText) : [] };
+		next.set(row.requestId, card);
+		if (prior.seq !== null && (prior.kind !== card.kind || prior.state !== card.state || prior.revision !== card.revision || prior.resultId !== card.resultId || prior.text !== card.text || prior.targetAgent !== card.targetAgent || !prior.listed)) changed.push(row.requestId);
+	}
+	return { cards: next, changed };
+}
+
+/** The visual tone of a state word: done, still moving, needs attention, or ended without a result. Never colour alone. */
+export function stateTone(state) {
+	if (state === "completed") return "ok";
+	if (state === null || UNCERTAIN_STATES.includes(state) || state === "waiting_owner") return "warn";
+	if (isTerminal(state)) return "danger";
+	return "busy";
+}
+
+export function stateLabel(state) {
+	return t(REQUEST_STATES.includes(state) ? `collab.state.${state}` : "collab.state.unconfirmed");
+}
+
+function agentName(agents, id) {
+	const row = Array.isArray(agents) ? agents.find((agent) => agent?.id === id) : null;
+	return isText(row?.name) && row.name ? row.name : null;
+}
+
+/**
+ * What one card shows. `ctx`: the agent list (names by id), the open conversation's agent id (null in main), main's
+ * name. The sender of an incoming request is its actor; an outgoing request's recipient is not in the stored event, so
+ * it reads as the other agent until the owner listing names it (F3 D5).
+ */
+export function cardView(card, ctx) {
+	const self = ctx.agentId === null ? ctx.mainName : agentName(ctx.agents, ctx.agentId) ?? t("collab.party.deleted");
+	const actor = card.actor;
+	const actorName = actor === null ? null : actor.kind === "main" ? ctx.mainName : agentName(ctx.agents, actor.id) ?? t("collab.party.deleted");
+	const outgoing = card.outgoing === true;
+	const from = outgoing ? self : actorName ?? t("collab.party.other");
+	const targetName = card.targetAgent === null ? null : agentName(ctx.agents, card.targetAgent) ?? t("collab.party.deleted");
+	const to = outgoing ? targetName ?? t("collab.party.other") : self;
+	const state = card.state;
+	const uncertain = state === null || UNCERTAIN_STATES.includes(state) || card.deliveryUnknown;
+	const notes = [];
+	if (card.deliveryUnknown) notes.push({ text: t("collab.note.deliveryUnknown"), error: true });
+	if (card.blocked !== null) notes.push({ text: t("collab.note.blocked", { code: card.blocked }), error: true });
+	if (state === "waiting_owner") notes.push({ text: t("collab.note.waitingOwner"), error: false });
+	if (state === "version_conflict") notes.push({ text: t("collab.note.versionConflict"), error: true });
+	if (state === "unresolved_delivery") notes.push({ text: t("collab.note.unresolvedDelivery"), error: true });
+	if (state === null) notes.push({ text: t("collab.note.unconfirmed"), error: false });
+	return {
+		requestId: card.requestId, outgoing, from, to, ts: card.ts,
+		title: t(outgoing ? "collab.title.sent" : "collab.title.received"),
+		kind: card.kind, kindLabel: card.kind === null ? null : t(`collab.kind.${card.kind}`),
+		state, stateLabel: stateLabel(state), tone: stateTone(state), uncertain,
+		text: card.text ?? "",
+		inputs: card.files.map((artifactId, index) => ({ artifactId, name: t("collab.file.input", { n: index + 1 }), bytes: null, sha256: null })),
+		result: card.result === null ? null : { text: card.result.text, files: card.result.files.map((file) => ({ ...file, size: file.bytes === null ? "" : formatBytes(file.bytes) })) },
+		replied: card.replied,
+		cancellable: state !== null && !isTerminal(state),
+		notes,
+	};
+}
+
+/** The cancel request for a card: the gateway compares the revision the screen last saw, so a card without one cannot ask yet. */
+export function cancelRequest(card) {
+	if (!card || typeof card.revision !== "number") return null;
+	return { method: "POST", path: `${REQUESTS_PATH}/${encodeURIComponent(card.requestId)}/cancel`, headers: { "content-type": "application/json" }, body: JSON.stringify({ expectedRevision: card.revision }) };
+}
+
+export function listingRequest(conv) {
+	return { method: "GET", path: `${REQUESTS_PATH}?conv=${encodeURIComponent(conv)}` };
+}
+
+export function artifactPath(artifactId) {
+	return `${ARTIFACTS_PATH}/${encodeURIComponent(artifactId)}`;
+}
+
+/**
+ * What a cancel answer means for the card and the line under it. 200 carries the gateway's receipt (state, revision);
+ * every refusal is a sentence, and the owner-helper refusal (503 owner_auth_unavailable) says the action is not
+ * available yet rather than pretending it worked.
+ */
+export function cancelOutcome(status, body) {
+	const code = isText(body?.error) ? body.error : null;
+	if (status === 200 && record(body) && isText(body.state)) {
+		const state = body.state, revision = typeof body.revision === "number" ? body.revision : null;
+		return { ok: true, state, revision, line: t(state === "cancelled" ? "collab.cancel.done" : state === "cancel_requested" ? "collab.cancel.requested" : "collab.cancel.state", { state: stateLabel(state) }) };
+	}
+	if (status === 0) return { ok: false, state: null, revision: null, line: t("collab.cancel.network") };
+	if (status === 503 && code === "owner_auth_unavailable") return { ok: false, state: null, revision: null, line: t("collab.cancel.unavailable") };
+	if (status === 401 || status === 403) return { ok: false, state: null, revision: null, line: t("collab.cancel.ownerRequired") };
+	if (status === 404) return { ok: false, state: null, revision: null, line: t("collab.cancel.notFound") };
+	if (status === 409) return { ok: false, state: null, revision: null, line: t("collab.cancel.conflict") };
+	return { ok: false, state: null, revision: null, line: t("collab.cancel.failed", { reason: code ?? `HTTP ${status}` }) };
+}
+
+/**
+ * What a download answer means. The bytes are saved only when the gateway's digest header equals the manifest's sha256
+ * (the header alone for an input file the manifest does not describe) and, where the browser could hash them (a secure
+ * context), the digest of what arrived equals it too; a mismatch is reported and nothing is saved.
+ */
+export function downloadOutcome(name, status, body, digests) {
+	const code = isText(body?.error) ? body.error : null;
+	if (status === 200) {
+		const reference = isText(digests.expected) ? digests.expected : digests.header;
+		const verified = isText(reference) && digests.header === reference && (digests.computed === null || digests.computed === reference);
+		return verified ? { ok: true, line: t("collab.download.done", { name }) } : { ok: false, line: t("collab.download.mismatch", { name }) };
+	}
+	if (status === 0) return { ok: false, line: t("collab.download.failed", { name, reason: t("collab.reason.network") }) };
+	if (status === 503 && code === "owner_auth_unavailable") return { ok: false, line: t("collab.download.unavailable") };
+	if (status === 401 || status === 403) return { ok: false, line: t("collab.download.failed", { name, reason: t("collab.reason.ownerRequired") }) };
+	if (status === 404) return { ok: false, line: t("collab.download.failed", { name, reason: t("collab.reason.notFound") }) };
+	if (status === 409) return { ok: false, line: t("collab.download.failed", { name, reason: t("collab.reason.changed") }) };
+	return { ok: false, line: t("collab.download.failed", { name, reason: code ?? `HTTP ${status}` }) };
+}
+
+export function listingOutcome(status, body) {
+	if (status === 200) return { ok: true, line: t("collab.recheck.done") };
+	const code = isText(body?.error) ? body.error : null;
+	return { ok: false, line: t("collab.recheck.failed", { reason: status === 0 ? t("collab.reason.network") : code ?? `HTTP ${status}` }) };
+}
+
+/**
+ * The directional targets check list (C-10): every other agent by name (never this agent itself), checked when its id is
+ * saved; a saved id the list does not carry (a deleted agent) stays checked and is marked missing, so the owner sees it
+ * and can uncheck it. Before the list is loaded only the saved ids are known.
+ */
+export function targetOptions(agents, selfId, saved) {
+	const savedIds = Array.isArray(saved) ? [...new Set(saved.filter((id) => isText(id) && id.trim()).map((id) => id.trim()))] : [];
+	if (!Array.isArray(agents)) return { loaded: false, options: savedIds.map((id) => ({ id, name: id, checked: true, missing: null })) };
+	const known = agents.filter((agent) => record(agent) && isText(agent.id) && agent.id !== selfId)
+		.map((agent) => ({ id: agent.id, name: isText(agent.name) && agent.name ? agent.name : agent.id, checked: savedIds.includes(agent.id), missing: false }))
+		.sort((a, b) => a.name.localeCompare(b.name, "ko"));
+	const missing = savedIds.filter((id) => !known.some((option) => option.id === id)).map((id) => ({ id, name: id, checked: true, missing: true }));
+	return { loaded: true, options: [...missing, ...known] };
+}
+
+/** The origin tag of a source/ file: what the owner uploaded, or a copy received through collaboration; nothing for other files. */
+export function fileOriginLabel(row) {
+	if (row?.origin === "collaboration-copy") return { origin: "collaboration-copy", text: t("agents.file.origin.copy"), tip: t("agents.file.origin.copy.tip") };
+	if (row?.origin === "user-upload") return { origin: "user-upload", text: t("agents.file.origin.upload"), tip: t("agents.file.origin.upload.tip") };
+	return null;
+}
+
+/** The delete confirmation of a collaboration copy also says what deleting the copy does not undo. */
+export function fileDeleteText(row) {
+	return row?.origin === "collaboration-copy" ? `${t("agents.file.delete.confirm")} ${t("agents.file.delete.copy")}` : t("agents.file.delete.confirm");
+}

package/web/decisions.d.ts

@@ -1,7 +1,8 @@
 import type {
-	DecisionAnswerRequest, DecisionCountersInfo, DecisionInfo, DecisionResponse,
+	ArtifactReviewInfo, DecisionAnswerRequest, DecisionCountersInfo, DecisionInfo, DecisionResponse,
 	DecisionsPageData, DecisionUpdatedData,
 } from "../src/protocol.ts";
+import type { ArtifactReviewSummary } from "../src/security-allow.ts";
 
 type AnswerMode = DecisionAnswerRequest["mode"];
 type Answer = DecisionResponse | { readonly cancelled: true };
@@ -86,7 +87,7 @@ export function finishDetailLoad(
 ): DetailResult;
 export function failDetailLoad(inbox: Inbox, id: string, generation: number): boolean;
 export function presentation(decision: DecisionInfo): {
-	readonly kind: "terminal" | "submitted" | "live" | "resume" | "permission" | "recheck" | "security";
+	readonly kind: "terminal" | "submitted" | "live" | "resume" | "permission" | "recheck" | "security" | "artifact-review";
 	readonly mode: AnswerMode | null;
 	readonly form: boolean;
 	readonly recheck: boolean;
@@ -109,6 +110,8 @@ export function buildRequest(
 		| [mode: "request_permission" | "recheck", response: undefined, newId?: () => string]
 ): DecisionAnswerRequest | null;
 export function interpretAnswerResponse(status: number, body: unknown): AnswerResult;
+/** 294 C3: the answer of a tool card (grant, action, migration) carries the owner client headers. */
+export function ownerAnswerRequired(decision: unknown): boolean;
 export function noteConflict(inbox: Inbox, decision: DecisionInfo, latest: DecisionInfo | null | undefined): void;
 export function reference(inbox: Inbox, decision: DecisionInfo): DraftReference | null;
 export function isReviewRequired(inbox: Inbox, id: string): boolean;
@@ -127,3 +130,37 @@ export const WORK_STATUS_LABELS: Readonly<Record<
 	"submitted" | "running" | "waiting" | "waiting_input" | "completed" | "failed" | "cancelled" | "unknown", string
 >>;
 export const ROUTE_LABELS: Readonly<Record<NonNullable<DecisionInfo["answerRoute"]>, string>>;
+
+/** Artifact review holds (agent-collaboration-292 owner gap): the owner card of a held files.read and its owner calls. */
+export const ARTIFACT_REVIEW_PURPOSE: "collaboration_artifact_review";
+export const ARTIFACT_HOLDS_PATH: "/api/agent-collaboration/holds";
+type ReviewChoice = "allow" | "deny";
+export function artifactReview(decision: Partial<DecisionInfo> | null | undefined): ArtifactReviewInfo | null;
+export function isArtifactReview(decision: Partial<DecisionInfo> | null | undefined): boolean;
+export function reviewFindingsText(summary: ArtifactReviewSummary | null | undefined): string;
+export function reviewUnscannedText(summary: ArtifactReviewSummary | null | undefined): string | null;
+export function reviewOutcomeText(review: { readonly state: string; readonly resumeState?: string | null }): string | null;
+export function artifactReviewView(decision: DecisionInfo, options?: { readonly agentName?: (id: string) => string; readonly mainName?: string }): {
+	readonly holdId: string;
+	readonly revision: number;
+	readonly state: ArtifactReviewInfo["state"];
+	readonly resumeState: ArtifactReviewInfo["resumeState"];
+	readonly title: string;
+	readonly chip: string | null;
+	readonly rows: ReadonlyArray<{ readonly key: "agent" | "file" | "part" | "findings"; readonly label: string; readonly value: string }>;
+	readonly warning: string | null;
+	readonly question: string | null;
+	readonly outcome: string | null;
+	readonly pending: boolean;
+	readonly choices: ReadonlyArray<{ readonly choice: ReviewChoice; readonly label: string; readonly cls: "ok" | "danger" }>;
+} | null;
+export function artifactReviewRequest(decision: DecisionInfo, choice: ReviewChoice, newId?: () => string): {
+	readonly method: "POST"; readonly path: string; readonly headers: Readonly<Record<string, string>>; readonly body: string;
+} | null;
+export function artifactReviewOutcome(status: number, body: unknown): {
+	readonly ok: boolean;
+	readonly kind: "allowed" | "denied" | "cancelled" | "network" | "unavailable" | "owner" | "gone" | "conflict" | "failed";
+	readonly revision: number | null;
+	readonly resumeState: string | null;
+	readonly line: string | null;
+};