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

package/web/agents.d.ts

@@ -1,5 +1,5 @@
 export type FieldOrigin = "package" | "defaults" | "agent" | "none";
-export type FieldWidget = "text" | "textarea" | "number" | "toggle" | "model" | "select" | "skills" | "group";
+export type FieldWidget = "text" | "textarea" | "number" | "toggle" | "model" | "select" | "skills" | "targets" | "group";
 export type FieldType = "string" | "integer" | "boolean" | "object" | "strings";
 export type EditorKind = "new" | "agent" | "defaults";
 
@@ -13,12 +13,16 @@ export interface AgentFieldMeta {
 	readonly applies: "gateway" | "extension";
 	readonly widget: FieldWidget;
 	readonly forbidden: boolean;
+	/** Kept out of the editor (the value stays in the source); sent by newer gateways, set by the web's presentation for schema. */
+	readonly hidden?: boolean;
 }
 
 /** The editor's labels and hints for one registry field name. */
 export interface FieldPresentation {
 	readonly label: string;
 	readonly help?: string;
+	readonly hidden?: boolean;
+	readonly widget?: FieldWidget;
 	readonly options?: readonly string[];
 	readonly min?: number;
 	readonly max?: number;
@@ -42,23 +46,36 @@ export interface AgentSummary {
 	readonly convId: string;
 	readonly definitionSha: string;
 	readonly stale: boolean;
+	/** "unknown" while the gateway could not learn which definition the open session applied (todo 3); the state is then stale. Other values are not a known state. */
+	readonly staleReason?: string;
 }
 
-/** GET /api/agents/:id: the summary with the definition text, the merged result and the field registry. */
+/** GET /api/agents/:id: the summary with the definition text, the merged result, the parsed shared layer and the field registry. */
 export interface AgentDetail extends AgentSummary {
 	readonly source: string;
 	readonly fields: Readonly<Record<string, unknown>>;
 	readonly body: string;
 	readonly defaultsBody: string;
+	/** defaults.md as the gateway parsed it: the layer its merge applied under the agent's own values (agent-ux todo 12 fix 2). */
+	readonly defaultsFields: Readonly<Record<string, unknown>>;
 	readonly origins: Readonly<Record<string, "package" | "defaults" | "agent">>;
 	readonly sha: string;
 	readonly registry: readonly AgentFieldMeta[];
 }
 
-/** GET and PUT /api/agents/defaults: the defaults.md text and the same field registry. */
+/** GET and PUT /api/agents/defaults: the defaults.md text, the same text as the gateway parsed it, and the same field registry. */
 export interface AgentDefaults {
 	readonly source: string;
+	readonly fields: Readonly<Record<string, unknown>>;
+	readonly registry: readonly AgentFieldMeta[];
+}
+
+/** What the create screen opens from: the defaults registry and parsed layer, and for a reopened draft its text and id (agent-ux todo 11). */
+export interface NewAgentInput {
 	readonly registry: readonly AgentFieldMeta[];
+	readonly defaultsFields?: Readonly<Record<string, unknown>>;
+	readonly source?: string;
+	readonly draftId?: string;
 }
 
 export interface ConversationRow {
@@ -81,8 +98,18 @@ export interface EditorState {
 	readonly registry: readonly AgentFieldRow[];
 	readonly id: string | null;
 	readonly name: string | null;
+	/** defaults.md as the gateway parsed it (the answer's `fields` or `defaultsFields`): the shared layer under this definition's own values; {} for the defaults editor. */
+	readonly defaults: Readonly<Record<string, unknown>>;
 	readonly convId: string | null;
 	readonly stale: boolean;
+	/** A new agent's draft id (todo 11); null for an existing agent and the defaults. */
+	readonly draftId: string | null;
+	/** The files a reopened draft had picked (names and sizes only); app.js shows them as "pick again". */
+	readonly draftFiles?: readonly { readonly name: string; readonly size: number }[];
+	/** The merged sha the gateway holds (an existing agent), compared with the save answer (todo 13). */
+	readonly definitionSha: string | null;
+	/** The gateway's text as sent; an untouched editor composes it byte for byte, so there is nothing to save. */
+	readonly serverSource: string | null;
 	readonly own: Record<string, unknown>;
 	readonly rawByKey: Readonly<Record<string, string>>;
 	readonly touched: ReadonlySet<string>;
@@ -92,13 +119,18 @@ export interface EditorState {
 	readonly preamble: string;
 	readonly body: string;
 	readonly bodyTouched: boolean;
+	/** The layers under the own values: the registry's package defaults with defaults.md over them. */
 	readonly inherited: Readonly<Record<string, unknown>>;
+	/** What the gateway merged for an existing agent (its own values included); {} for the other kinds. */
+	readonly merged: Readonly<Record<string, unknown>>;
 	readonly origins: Readonly<Record<string, string>>;
 	readonly dirty: boolean;
 }
 
 export type EditorRow =
 	| { readonly kind: "group"; readonly name: string; readonly label: string; readonly help: string }
+	/** A prohibited field: drawn as a switch that cannot be turned on, with the reason in `help`; never written to the source. */
+	| { readonly kind: "forbidden"; readonly name: string; readonly label: string; readonly help: string }
 	| {
 		readonly kind: "field";
 		readonly name: string;
@@ -121,7 +153,7 @@ export type EditorRow =
 /** What widgetValue() reads from a registry row or an editor field row. */
 export type WidgetSpec = Pick<AgentFieldRow, "widget" | "required" | "label"> & Partial<Pick<AgentFieldRow, "options" | "min" | "max">>;
 export interface EditorError { readonly name: string; readonly message: string }
-export interface ApiRequest { readonly method: "GET" | "POST" | "PUT"; readonly path: string; readonly headers?: Readonly<Record<string, string>>; readonly body?: string }
+export interface ApiRequest { readonly method: "GET" | "POST" | "PUT" | "DELETE"; readonly path: string; readonly headers?: Readonly<Record<string, string>>; readonly body?: string }
 
 export interface SidebarItem {
 	readonly convId: string;
@@ -142,29 +174,62 @@ export interface SidebarView {
 	readonly pending: ReadonlyMap<string, number>;
 }
 
-export interface HeaderView { readonly agent: boolean; readonly agentId: string | null; readonly icon: string; readonly name: string; readonly stale: boolean }
+export interface HeaderView { readonly agent: boolean; readonly agentId: string | null; readonly icon: string; readonly name: string; readonly stale: boolean; readonly staleReason: "unknown" | null }
+/** Bug 283: the header's definition status line and the new-session button's state; the texts are keys of web/i18n/main.js. */
+export interface StaleNotice {
+	readonly shown: boolean;
+	readonly textKey: "agent.stale.changed" | "agent.stale.unknown" | null;
+	readonly attention: boolean;
+	readonly labelKey: "head.newSession" | "head.newSession.apply";
+	readonly confirmKey: "head.newSession.confirm" | "head.newSession.confirm.apply";
+}
+/** The speaker of a conversation's bot rows and sidebar profile: a text `icon` for an agent, an `iconUrl` picture for main. */
+export interface SpeakerView { readonly agent: boolean; readonly agentId: string | null; readonly name: string; readonly icon: string | null; readonly iconUrl: string | null }
 export interface TrashRow { readonly entry: string; readonly id: string | null; readonly name: string; readonly description: string; readonly icon: string; readonly deletedAt: string | null }
-export interface FileRow { readonly path: string; readonly type: "file" | "directory"; readonly size: number; readonly depth: number; readonly name: string; readonly label: string; readonly source: boolean }
+export type KnowledgeArea = "source" | "outputs" | "notes" | "memory" | "other";
+export type FileOrigin = "user-upload" | "collaboration-copy";
+export interface FileRow { readonly path: string; readonly type: "file" | "directory"; readonly size: number; readonly depth: number; readonly name: string; readonly label: string; readonly source: boolean; readonly area: KnowledgeArea; readonly modifiedAt: string | null; readonly origin?: FileOrigin | null }
+export interface FileAreas { readonly source: FileRow[]; readonly outputs: FileRow[]; readonly notes: FileRow[] }
+/** A deleted knowledge file as the gateway archives it (agent-ux todo 16). */
+export interface FileTrashRow { readonly entry: string; readonly path: string; readonly name: string; readonly area: KnowledgeArea; readonly size: number; readonly label: string; readonly deletedAt: string | null }
+/** One accepted upload as the status line reports it: the picked name, the name the gateway saved, and its size. */
+export interface SavedUpload { readonly name: string; readonly savedName: string; readonly size: number }
+/** One queued upload (agent-ux todo 14): the picked file, its state, progress 0..1, the refusal code and sentence, and the name the gateway saved it under. */
+export type UploadStatus = "queued" | "waiting" | "uploading" | "done" | "failed";
+export interface UploadRow {
+	readonly key: string;
+	readonly file: unknown;
+	readonly name: string;
+	readonly size: number;
+	readonly status: UploadStatus;
+	readonly progress: number;
+	readonly error: string | null;
+	readonly errorLine: string | null;
+	readonly savedName: string | null;
+}
+export interface UploadPatch { readonly status?: UploadStatus; readonly progress?: number; readonly error?: string | null; readonly errorLine?: string | null; readonly savedName?: string | null }
+export interface UploadSummary { readonly total: number; readonly done: number; readonly failed: number; readonly waiting: number; readonly uploading: number; readonly active: boolean }
 export interface AgentUpdateResult<P, C> { readonly agents: readonly P[]; readonly conversations: readonly C[]; readonly removedConv: string | null; readonly restoredConv: string | null }
 
 export const AGENTS_PATH: string;
 export const DEFAULTS_PATH: string;
 export const TRASH_PATH: string;
+export const DRAFTS_PATH: string;
+export const DRAFT_DELAY_MS: number;
 export const AGENT_MAX_BYTES: number;
 export const DESCRIPTION_MAX: number;
 export const MEMORY_MAX_BYTES: number;
 export const THINKING_LEVELS: readonly string[];
 export const ORIGIN_LABELS: Readonly<Record<FieldOrigin, string>>;
 export const DEFAULT_ICON: string;
-export const STALE_LABEL: string;
 export const STALE_TITLE: string;
 export const DELETE_HINT: string;
 export const EMPTY_AGENTS_LINE: string;
 export const EMPTY_TRASH_LINE: string;
-export const EMPTY_FILES_LINE: string;
-export const NEW_AGENT_BODY: string;
 export const FIELD_PRESENTATION: Readonly<Record<string, FieldPresentation>>;
 
+/** The role-instruction guide's four headings in the UI language (agent-ux todo 9). */
+export function roleGuideItems(): { readonly key: "scope" | "tasks" | "limits" | "address"; readonly label: string; readonly text: string }[];
 export function fieldAt(fields: unknown, name: string): unknown;
 export function editorFields(registry: readonly AgentFieldMeta[] | null | undefined): AgentFieldRow[];
 export function topLevelKeys(registry: readonly AgentFieldMeta[]): string[];
@@ -172,30 +237,142 @@ export function parseYaml(text: string): unknown;
 export function emitScalar(value: unknown): string;
 export function emitEntry(key: string, value: unknown): string;
 export function splitSource(source: string): SourceSplit;
-export function editorState(detail: Partial<AgentDetail> | Partial<AgentDefaults> | null | undefined, kind?: EditorKind): EditorState;
+/** What the editor opens from: a gateway answer or the create screen's input; the shared layer arrives parsed by the gateway (`defaultsFields`), never as text. */
+export type EditorInput = Partial<AgentDetail> | Partial<AgentDefaults> | Partial<NewAgentInput>;
+export function editorState(detail: EditorInput | null | undefined, kind?: EditorKind): EditorState;
 export function packageDefaults(registry: readonly AgentFieldMeta[]): Record<string, unknown>;
 export function editorRows(state: EditorState): EditorRow[];
 export function widgetValue(field: WidgetSpec, input: unknown): { value?: unknown; error?: string };
+export const DRAFT_REOPEN_WAIT_MS: number;
+export const PREVIEW_PATH: string;
+export const PREVIEW_DELAY_MS: number;
+/** The can/cannot box's state (agent-ux todo 12): the merged fields the gateway answered for the editor's current text, or why there are none (`failed`: the request did not bring an answer for that text). */
+export interface PreviewState { readonly status: "loading" | "ready" | "unavailable" | "failed"; readonly fields: Readonly<Record<string, unknown>> | null }
+/** POST /api/agents/preview with the editor's composed text; the gateway evaluates it as a save would and writes nothing. */
+export function previewRequest(state: EditorState): ApiRequest;
+/** The box's state after an answer: ready with the gateway's fields, unavailable for refused text, failed for a request that brought no readable answer. */
+export function previewState(answer: unknown): PreviewState;
+/** One line of the can/cannot box (agent-ux todo 12); `tip` is the tooltip detail. */
+export interface CapabilityItem { readonly key: string; readonly text: string; readonly tip: string }
+export function capabilities(merged: Record<string, unknown>): { readonly can: CapabilityItem[]; readonly cannot: CapabilityItem[] };
+/** One row of the allowed-skills check list (agent-ux todo 10); `installed` is null while the list could not be loaded. */
+export interface SkillOption {
+	readonly name: string;
+	readonly checked: boolean;
+	readonly installed: boolean | null;
+	readonly description: string;
+}
+export function skillOptions(commands: unknown, saved: unknown): { readonly loaded: boolean; readonly options: SkillOption[] };
 export function setField(state: EditorState, name: string, value: unknown): EditorState;
 export function clearField(state: EditorState, name: string): EditorState;
 export function setBody(state: EditorState, body: string): EditorState;
 export function setUnknownRaw(state: EditorState, unknownRaw: string): EditorState;
 export function composeSource(state: EditorState): string;
+export function editorUpdateAction(editor: { readonly kind?: unknown; readonly id?: unknown; readonly definitionSha?: unknown; readonly dirty?: unknown } | null | undefined, data: unknown): "reload" | "changed" | null;
 export function validateEditor(state: EditorState): EditorError[];
 export function saveRequest(state: EditorState): ApiRequest;
+/** An injectable scheduler, so tests count timer calls exactly. */
+export interface DebounceOptions { readonly delayMs?: number; readonly setTimer?: (fn: () => void, ms: number) => unknown; readonly clearTimer?: (handle: unknown) => void }
+/**
+ * The create screen's draft autosave (agent-ux todo 11, 18): durable, one lane per draft id. A state whose quiet period ended, or
+ * that was flushed, is due and always reaches the server, in order, behind that draft's request on the wire.
+ */
+export interface DraftSaver<S extends { readonly draftId: string | null } = EditorState> {
+	touch(state: S): void;
+	/** Makes every waiting state due at once (the dialog closes); true when one was waiting. */
+	flush(): boolean;
+	/** Drains that draft's waiting writes; false means its last write failed, not that it is still pending. */
+	settle(draftId: string | null): Promise<boolean>;
+	/** The newest state this page holds for that draft (waiting, due or sent), or null. */
+	latest(draftId: string | null): S | null;
+	/** A state waits for its timer or for its draft's wire. */
+	readonly pending: boolean;
+	/** Resolves once every request on the wire has answered; nothing is dropped. */
+	readonly idle: Promise<void>;
+}
+export function createDraftSaver<S extends { readonly draftId: string | null } = EditorState>(save: (state: S) => void | boolean | Promise<unknown>, options?: DebounceOptions): DraftSaver<S>;
+/**
+ * The can/cannot box's preview requests (agent-ux todo 12, 18): disposable, owned by one editor at a time. `request` gets the owner
+ * token of the moment it goes out; `discard()` drops what waits and moves the token on, so an earlier owner's answer is not applied.
+ */
+export interface PreviewRequester<S = EditorState> {
+	touch(state: S): void;
+	flush(): boolean;
+	discard(): void;
+	owns(token: number): boolean;
+	readonly token: number;
+	/** A state waits for its timer or for the wire. */
+	readonly pending: boolean;
+	/** Resolves once the request on the wire (if any) has answered. */
+	readonly idle: Promise<void>;
+}
+export function createPreviewRequester<S = EditorState>(request: (state: S, token: number) => void | Promise<unknown>, options?: DebounceOptions): PreviewRequester<S>;
+export function newDraftId(random?: () => number): string;
+export function draftRequest(state: EditorState, files?: readonly { readonly name: string; readonly size: number }[]): ApiRequest;
+export interface DraftRow { readonly id: string; readonly name: string | null; readonly updatedAt: string }
+export function draftRows(list: unknown): DraftRow[];
+export function draftLoadRequest(id: string): ApiRequest;
+export function discardDraftRequest(id: string): ApiRequest;
 export function deleteEnabled(typed: string, name: string | null | undefined): boolean;
 export function deleteRequest(id: string, name: string): ApiRequest;
 export function cloneRequest(id: string): ApiRequest;
-export function restoreRequest(entry: string): ApiRequest;
+export function restoreRequest(entry: string, options?: { readonly newId?: boolean }): ApiRequest;
+export type RestoreOutcome =
+	| { readonly kind: "restored"; readonly detail: AgentDetail }
+	| { readonly kind: "conflict"; readonly id: string }
+	| { readonly kind: "error"; readonly message: string };
+export function restoreOutcome(status: number, body: unknown): RestoreOutcome;
+export const UPLOAD_MAX_BYTES: number;
+export function uploadRows(files: ArrayLike<{ readonly name?: unknown; readonly size?: unknown }> | null | undefined): UploadRow[];
+export function uploadErrorLine(code: string | null | undefined): string;
+export function queuedUploadRows(files: ArrayLike<{ readonly name?: unknown; readonly size?: unknown }> | null | undefined): UploadRow[];
+export function draftFileList(rows: readonly UploadRow[]): { readonly name: string; readonly size: number }[];
+export function uploadsAfterCreate(body: unknown, rows: readonly UploadRow[] | null | undefined): { readonly id: string; readonly rows: UploadRow[] } | null;
+export function nextUpload(rows: readonly UploadRow[]): UploadRow | null;
+export function advanceUpload(rows: readonly UploadRow[], key: string, patch: UploadPatch): UploadRow[];
+export function retryUpload(rows: readonly UploadRow[], key: string): UploadRow[];
+export function uploadSummary(rows: readonly UploadRow[]): UploadSummary;
+export function uploadStateLine(row: UploadRow): string;
 export function filesPath(id: string): string;
 export function sourceUploadPath(id: string): string;
 export function errorLine(body: unknown, status: number): string;
+export function unchangedSource(state: EditorState): boolean;
+export function saveOutcome(state: EditorState, body: unknown): { readonly changed: boolean; readonly stale: boolean };
+/** agent-ux todo 21: what "지금 적용" applies after a changed save of a stale agent. */
+export interface ApplyTarget { readonly agentId: string; readonly convId: string; readonly sha: string }
+export type ApplyResult = "applied" | "mismatch" | "open_failed" | "turn_running" | "unconfirmed";
+export function applyNowTarget(outcome: { readonly changed: boolean; readonly stale: boolean }, body: unknown): ApplyTarget | null;
+export function applyNowShown(target: ApplyTarget | null, agents: readonly { readonly id?: string; readonly stale?: boolean }[]): boolean;
+export function rotateRequest(convId: string, view: Pick<HeaderView, "agent" | "stale">): { readonly type: "conversation.rotate"; readonly conv: string; readonly open?: true };
+export const APPLY_WAIT_MS: number;
+export function applyWatch(target: ApplyTarget): (event: { readonly type?: string; readonly conv?: string; readonly data?: unknown } | null | undefined) => Exclude<ApplyResult, "unconfirmed"> | null;
+export function applyLine(result: string): string;
+export function freshListAnswer(sentStamp: number, stampNow: number): boolean;
+export function reconcileAgents(event: { readonly type?: string; readonly conv?: string; readonly data?: unknown } | null | undefined, agents: readonly { readonly convId?: string }[]): boolean;
+/** The error app.js agentApi throws: the gateway's code and field, the HTTP status, or `network` when nothing answered. */
+export interface RequestFailure { readonly code?: string | null; readonly field?: string | null; readonly status?: number; readonly network?: boolean; readonly message?: string }
+export function saveErrorLine(error: RequestFailure | Error | unknown, fields?: readonly { readonly name: string; readonly label: string }[]): string;
 export function applyAgentUpdate<P extends { id: string; convId?: string }, C extends ConversationRow>(agents: readonly P[], conversations: readonly C[], data: unknown, now?: number): AgentUpdateResult<P | AgentSummary, C | ConversationRow>;
-export function applyAgentApplied<P extends { convId: string; definitionSha: string; stale: boolean }>(agents: readonly P[], convId: string, data: unknown): P[];
+export function applyAgentApplied<P extends { convId: string; definitionSha: string; stale: boolean; staleReason?: string }>(agents: readonly P[], convId: string, data: unknown): Array<Omit<P, "staleReason"> & { readonly staleReason?: string }>;
 export function mainConversations<C extends ConversationRow>(conversations: readonly C[]): C[];
 export function shownConversation(conversations: readonly ConversationRow[], id: string): string;
 export function agentInitial(name: unknown): string;
 export function sidebarItems(conversations: readonly ConversationRow[], agents: readonly Partial<AgentSummary>[], view: SidebarView): SidebarItem[];
 export function headerView(conv: ConversationRow | null | undefined, agents: readonly Partial<AgentSummary>[]): HeaderView;
+export function staleNotice(view: Pick<HeaderView, "stale" | "staleReason">): StaleNotice;
+export function speakerView(conv: ConversationRow | null | undefined, agents: readonly Partial<AgentSummary>[], main: { readonly name: string; readonly iconUrl?: string | null }): SpeakerView;
 export function trashRows(entries: unknown): TrashRow[];
 export function fileRows(entries: unknown): FileRow[];
+export function fileAreas(rows: readonly FileRow[]): FileAreas;
+export function deletableFile(row: FileRow): boolean;
+export function downloadable(row: FileRow): boolean;
+export function downloadPath(id: string, path: string): string;
+export function modifiedLabel(modifiedAt: string | null | undefined, locale: string): string;
+export function turnEndRefreshes(editor: { readonly kind: string; readonly id?: string | null; readonly convId?: string | null } | null | undefined, conv: string | null | undefined): boolean;
+export function fileDeleteRequest(id: string, path: string): ApiRequest;
+export function fileTrashPath(id: string): string;
+export function fileRestoreRequest(id: string, entry: string): ApiRequest;
+export function fileTrashRows(entries: unknown): FileTrashRow[];
+export function fileTrashLabel(count: number): string;
+export function uploadedLine(saved: readonly SavedUpload[]): string;
+export function lastDailyLine(lastDaily: string | null | undefined): string;