@timurproko/a1 0.1.1-dev.1 → 0.1.1-dev.3

package/README.md

@@ -44,6 +44,19 @@ npm start
 
 A1 control state uses `%APPDATA%\\A1` and `%LOCALAPPDATA%\\A1` on Windows, and the `a1` directory under XDG config/data/runtime roots on Unix. Override it only with declared `A1_*` variables such as `A1_CONFIG_DIR`, `A1_DATA_DIR`, `A1_RUNTIME_DIR`, `A1_DATABASE_PATH`, and `A1_ENDPOINT`. Pi profile roots remain `~/.a1/agent`, `~/.pi/agent`, and `~/.a1/sandbox`. This is a no-migration identity hard cut; see [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md#identity-hard-cut-and-cleanup) before removing obsolete control state.
 
+### Branch lifecycle
+
+Create every topic branch and every `milestone/<name>` work branch from `develop`; never implement directly on `develop` or `master`. A source branch is closed only after this sequence completes:
+
+1. Validate the source branch with its required gates.
+2. Merge it into `develop` and push the merged `develop` commit.
+3. Switch to `develop`.
+4. Preview the exact cleanup set with `npm run branches:prune -- --branch <source>`.
+5. Safely delete the reviewed local source with `npm run branches:prune -- --apply --branch <source>`.
+6. When the non-protected remote source exists, delete it in the same cleanup with `npm run branches:prune -- --apply --branch <source> --remote origin`.
+
+The command defaults to a dry run against `develop`. It always retains `develop`, `master`, the checked-out branch, explicitly protected branches, and branches whose tips are not ancestors of the integration target. Apply mode uses only Git safe deletion (`git branch -d`), never force deletion. Use `--base <branch>` for another explicit integration target, `--protect <branch>` for additional protection, and `--json` for machine-readable review.
+
 Run the non-desktop gates with:
 
 ```sh

package/bin/a1-ui.js

@@ -4,11 +4,11 @@ const { runSelectedInteractiveRuntime } = await import("../dist/src/features/lau
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
   ownedUi: async () => {
-    const [{ runOwnedUi }, { composeOwnedUiApplication }] = await Promise.all([
+    const [{ runOwnedUi }, { composeStructuredWorkspaceApplication }] = await Promise.all([
       import("../dist/src/features/owned-ui/index.js"),
       import("../dist/src/composition/index.js"),
     ]);
-    const application = await composeOwnedUiApplication({ cwd: process.cwd() });
+    const application = await composeStructuredWorkspaceApplication({ cwd: process.cwd() });
     return await runOwnedUi({ application });
   },
   transparent: async profileId => {

package/dist/src/composition/index.d.ts

@@ -1,6 +1,9 @@
 import { type AgentEnginePort } from "../foundation/agent-engine-contracts/index.js";
 import { type PiEngineAdapter } from "../foundation/pi-engine-adapter/index.js";
 import { type OwnedUiApplicationPort, type PresentationComponentPort, type PresentationRuntimePort, type PresentationTerminalPort } from "../foundation/presentation-contracts/index.js";
+import { StructuredWorkspaceTabs, type StructuredWorkspaceLimits } from "../features/workspace/index.js";
+import { StructuredWorkspaceApplication } from "./structured-workspace-application.js";
+export * from "./structured-workspace-application.js";
 export interface ProcessCompositionOptions {
     readonly cwd?: string;
     readonly sessionId?: string;
@@ -14,6 +17,21 @@ export interface OwnedUiCompositionOptions {
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
 }
 export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
+export interface StructuredWorkspaceCompositionOptions {
+    readonly cwd?: string;
+    readonly workspaceId?: string;
+    readonly limits?: Partial<StructuredWorkspaceLimits>;
+    readonly createEngine?: (agentId: string) => Promise<AgentEnginePort>;
+    readonly createPiAdapter?: (agentId: string) => Promise<PiEngineAdapter>;
+}
+export declare function composeStructuredWorkspace(options?: StructuredWorkspaceCompositionOptions): StructuredWorkspaceTabs;
+export interface StructuredWorkspaceApplicationCompositionOptions extends StructuredWorkspaceCompositionOptions {
+    readonly terminal?: PresentationTerminalPort;
+    readonly mode?: "regular" | "fullscreen";
+    readonly initialAgentId?: string;
+    readonly initialAgentName?: string;
+}
+export declare function composeStructuredWorkspaceApplication(options?: StructuredWorkspaceApplicationCompositionOptions): Promise<StructuredWorkspaceApplication>;
 export interface ProcessComposition {
     readonly engine: AgentEnginePort;
     createPresentation(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;

package/dist/src/composition/index.js

@@ -3,6 +3,9 @@ import { createPiEngineAdapter } from "../foundation/pi-engine-adapter/index.js"
 import { createPiPresentationRuntime, createPiTerminalBridge } from "../foundation/pi-tui-runtime-adapter/index.js";
 import { assertPresentationComponent, assertPresentationRuntime, } from "../foundation/presentation-contracts/index.js";
 import { OwnedUiSessionShell } from "../foundation/pi-owned-ui-integration/index.js";
+import { StructuredWorkspaceTabs, } from "../features/workspace/index.js";
+import { StructuredWorkspaceApplication } from "./structured-workspace-application.js";
+export * from "./structured-workspace-application.js";
 const CAPABILITIES = {
     contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
     commands: ["prompt", "steer", "follow-up", "abort", "retry", "compact", "bash", "replace-session"],
@@ -25,6 +28,39 @@ export async function composeOwnedUiApplication(options = {}) {
         dispose: () => shell.dispose(),
     };
 }
+export function composeStructuredWorkspace(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const createEngine = options.createEngine ?? (async (agentId) => {
+        const sessionId = `${agentId}.session`;
+        const adapter = options.createPiAdapter
+            ? await options.createPiAdapter(agentId)
+            : await createPiEngineAdapter({ cwd, sessionId });
+        return new PiAgentEngineBridge(adapter, cwd);
+    });
+    return new StructuredWorkspaceTabs({
+        cwd,
+        createEngine,
+        ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+    });
+}
+export async function composeStructuredWorkspaceApplication(options = {}) {
+    const workspace = composeStructuredWorkspace(options);
+    const created = await workspace.createAgent({
+        id: options.initialAgentId ?? "agent-1",
+        displayName: options.initialAgentName ?? "Agent 1",
+    });
+    if (created.kind === "rejected") {
+        await workspace.dispose();
+        throw new Error(`could not create the initial structured workspace agent: ${created.diagnostic}`);
+    }
+    return new StructuredWorkspaceApplication({
+        workspace,
+        cwd: options.cwd ?? process.cwd(),
+        ...(options.terminal === undefined ? {} : { terminal: options.terminal }),
+        ...(options.mode === undefined ? {} : { mode: options.mode }),
+    });
+}
 export async function composeProcess(options = {}) {
     let engine = options.engine;
     if (!engine) {

package/dist/src/composition/structured-workspace-application.d.ts

@@ -0,0 +1,38 @@
+import { OwnedUiSessionShellRoot } from "../foundation/pi-owned-ui-integration/index.js";
+import { PiTuiRuntimeAdapter, type PiTuiComponentPort } from "../foundation/pi-tui-runtime-adapter/index.js";
+import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../foundation/presentation-contracts/index.js";
+import { type StructuredWorkspaceTabs } from "../features/workspace/index.js";
+export interface StructuredWorkspaceApplicationOptions {
+    readonly workspace: StructuredWorkspaceTabs;
+    readonly cwd: string;
+    readonly terminal?: PresentationTerminalPort;
+    readonly mode?: "regular" | "fullscreen";
+}
+export declare class StructuredWorkspaceApplication implements OwnedUiApplicationPort {
+    #private;
+    readonly workspace: StructuredWorkspaceTabs;
+    readonly root: OwnedUiSessionShellRoot;
+    readonly runtime: PiTuiRuntimeAdapter;
+    readonly component: StructuredWorkspaceRootComponent;
+    constructor(options: StructuredWorkspaceApplicationOptions);
+    get disposed(): boolean;
+    start(): void;
+    flush(): Promise<void>;
+    waitUntilStopped(): Promise<void>;
+    submit(raw: string): Promise<void>;
+    switchRelative(direction: -1 | 1): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare class StructuredWorkspaceRootComponent implements PiTuiComponentPort {
+    readonly workspace: StructuredWorkspaceTabs;
+    readonly sessionRoot: OwnedUiSessionShellRoot;
+    readonly onSwitch: (direction: -1 | 1) => void;
+    readonly onEditorChange: (text: string) => void;
+    readonly notice: () => string | null;
+    constructor(workspace: StructuredWorkspaceTabs, sessionRoot: OwnedUiSessionShellRoot, onSwitch: (direction: -1 | 1) => void, onEditorChange: (text: string) => void, notice: () => string | null);
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+    setFocused(focused: boolean): void;
+    dispose(): void;
+}

package/dist/src/composition/structured-workspace-application.js

@@ -0,0 +1,261 @@
+import { OWNED_UI_CONTRACT_VERSION, } from "../foundation/owned-ui-contracts/index.js";
+import { OwnedUiSessionShellRoot } from "../foundation/pi-owned-ui-integration/index.js";
+import { createPiTerminalBridge, PiTuiRuntimeAdapter, } from "../foundation/pi-tui-runtime-adapter/index.js";
+import {} from "../features/workspace/index.js";
+export class StructuredWorkspaceApplication {
+    workspace;
+    root;
+    runtime;
+    component;
+    #unsubscribe;
+    #resolveStopped;
+    #stopped;
+    #notice = null;
+    #disposed = false;
+    #started = false;
+    #agentSequence;
+    constructor(options) {
+        this.workspace = options.workspace;
+        const initial = selectedPanel(options.workspace.view());
+        if (!initial)
+            throw new TypeError("structured workspace application requires an initial agent tab");
+        this.#agentSequence = options.workspace.view().panels.length;
+        this.#stopped = new Promise(resolve => { this.#resolveStopped = resolve; });
+        this.root = new OwnedUiSessionShellRoot(toOwnedView(options.workspace.view(), initial, null, 80, 24), options.cwd, {
+            getColumns: () => this.runtime?.viewport().columns ?? options.terminal?.columns ?? 80,
+            getRows: () => this.runtime?.viewport().rows ?? options.terminal?.rows ?? 24,
+            requestRender: () => this.runtime?.requestRender(),
+            onSubmit: text => { void this.submit(text); },
+            onInterrupt: () => { this.#notice = "Use /agent stop to stop the selected agent."; this.runtime?.requestRender(); },
+            onClear: () => { this.root.editor.setText(""); this.runtime?.requestRender(); },
+            onExit: () => { void this.dispose(); },
+            onModelSelect: () => { this.#notice = "Model selection remains scoped to each structured agent session."; this.runtime?.requestRender(); },
+            onThinkingCycle: () => { this.#notice = "Thinking settings remain scoped to each structured agent session."; this.runtime?.requestRender(); },
+        });
+        this.component = new StructuredWorkspaceRootComponent(this.workspace, this.root, direction => { void this.switchRelative(direction); }, text => this.#saveEditor(text), () => this.#notice);
+        this.runtime = new PiTuiRuntimeAdapter({
+            root: this.component,
+            mode: options.mode ?? "regular",
+            ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+            hardwareCursor: true,
+            mouse: false,
+        });
+        this.#unsubscribe = this.workspace.subscribe(view => this.#sync(view));
+    }
+    get disposed() { return this.#disposed; }
+    start() {
+        if (this.#started || this.#disposed)
+            return;
+        this.#started = true;
+        this.runtime.start();
+        this.#sync(this.workspace.view());
+    }
+    async flush() {
+        await this.workspace.flush();
+        this.#sync(this.workspace.view());
+    }
+    waitUntilStopped() { return this.#stopped; }
+    async submit(raw) {
+        const input = raw.trim();
+        if (!input)
+            return;
+        if (input === "/agent" || input.startsWith("/agent ")) {
+            await this.#agentCommand(input.slice("/agent".length).trim());
+            return;
+        }
+        const selected = selectedPanel(this.workspace.view());
+        if (!selected)
+            return;
+        this.workspace.setEditorText(selected.agentId, input);
+        const result = await this.workspace.sendPrompt(selected.agentId, input);
+        this.#notice = result.kind === "rejected" ? result.diagnostic : null;
+        this.#sync(this.workspace.view());
+    }
+    async switchRelative(direction) {
+        const view = this.workspace.view();
+        if (view.panels.length < 2)
+            return;
+        this.#saveEditor(this.root.editor.getText());
+        const current = Math.max(0, view.panels.findIndex(panel => panel.selected));
+        const next = (current + direction + view.panels.length) % view.panels.length;
+        const target = view.panels[next];
+        if (target)
+            await this.workspace.selectAgent(target.agentId);
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#unsubscribe();
+        const failures = [];
+        await this.runtime.stop().catch(error => failures.push(error));
+        await this.workspace.dispose().catch(error => failures.push(error));
+        this.#resolveStopped?.();
+        if (failures.length > 0)
+            throw new AggregateError(failures, "structured workspace application disposal failed");
+    }
+    async #agentCommand(argument) {
+        const [command = "list", ...rest] = argument.split(/\s+/).filter(Boolean);
+        const view = this.workspace.view();
+        const selected = selectedPanel(view);
+        if (command === "new") {
+            this.#agentSequence += 1;
+            const id = `agent-${this.#agentSequence}`;
+            const displayName = rest.join(" ") || `Agent ${this.#agentSequence}`;
+            const created = await this.workspace.createAgent({ id, displayName });
+            if (created.kind === "applied")
+                await this.workspace.selectAgent(id);
+            this.#notice = created.kind === "rejected" ? created.diagnostic : `Created ${created.value.agentId}.`;
+        }
+        else if (command === "next" || command === "previous" || command === "prev") {
+            await this.switchRelative(command === "next" ? 1 : -1);
+            this.#notice = null;
+        }
+        else if (command === "select") {
+            const target = rest[0];
+            const selectedResult = target ? await this.workspace.selectAgent(target) : null;
+            this.#notice = selectedResult === null ? "Usage: /agent select <id>" : selectedResult.kind === "rejected" ? selectedResult.diagnostic : null;
+        }
+        else if (command === "stop") {
+            const result = selected ? await this.workspace.stopAgent(selected.agentId) : null;
+            this.#notice = result === null ? "No agent selected." : result.kind === "rejected" ? result.diagnostic : `Stopped ${selected.agentId}.`;
+        }
+        else if (command === "restart") {
+            const result = selected ? await this.workspace.restartAgent(selected.agentId) : null;
+            this.#notice = result === null ? "No agent selected." : result.kind === "rejected" ? result.diagnostic : `Restarted ${selected.agentId}.`;
+        }
+        else if (command === "remove") {
+            if (!selected)
+                this.#notice = "No agent selected.";
+            else {
+                if (selected.lifecycle !== "stopped" && selected.lifecycle !== "failed")
+                    await this.workspace.stopAgent(selected.agentId);
+                const result = await this.workspace.removeAgent(selected.agentId);
+                this.#notice = result.kind === "rejected" ? result.diagnostic : `Removed ${selected.agentId}.`;
+            }
+        }
+        else if (command === "list") {
+            this.#notice = view.tabs.length === 0 ? "No managed agents." : view.tabs.map(tab => `${tab.selected ? "*" : " "}${tab.agentId}:${tab.label}`).join("  ");
+        }
+        else {
+            this.#notice = "Usage: /agent [list|new [name]|next|prev|select <id>|stop|restart|remove]";
+        }
+        this.#sync(this.workspace.view());
+    }
+    #saveEditor(text) {
+        const selected = selectedPanel(this.workspace.view());
+        if (selected)
+            this.workspace.setEditorText(selected.agentId, text);
+    }
+    #sync(view) {
+        const selected = selectedPanel(view);
+        if (!selected)
+            return;
+        const viewport = this.runtime?.viewport() ?? { columns: 80, rows: 24 };
+        this.root.update(toOwnedView(view, selected, this.#notice, viewport.columns, viewport.rows));
+        if (this.root.editor.getText() !== selected.editorText)
+            this.root.editor.setText(selected.editorText);
+        this.component.invalidate();
+        this.runtime?.requestRender();
+    }
+}
+export class StructuredWorkspaceRootComponent {
+    workspace;
+    sessionRoot;
+    onSwitch;
+    onEditorChange;
+    notice;
+    constructor(workspace, sessionRoot, onSwitch, onEditorChange, notice) {
+        this.workspace = workspace;
+        this.sessionRoot = sessionRoot;
+        this.onSwitch = onSwitch;
+        this.onEditorChange = onEditorChange;
+        this.notice = notice;
+    }
+    render(width) {
+        const view = this.workspace.view();
+        const tabLine = truncate(view.tabs.map(tab => `${tab.selected ? "[" : " "}${tab.label}${tab.selected ? "]" : " "}`).join("  "), width);
+        const notice = this.notice();
+        return [tabLine, ...(notice ? [truncate(notice, width)] : []), ...this.sessionRoot.render(width)];
+    }
+    handleInput(data) {
+        if (data === "\x1b[6;5~" || data === "\x1b[1;3C") {
+            this.onEditorChange(this.sessionRoot.editor.getText());
+            this.onSwitch(1);
+            return;
+        }
+        if (data === "\x1b[5;5~" || data === "\x1b[1;3D") {
+            this.onEditorChange(this.sessionRoot.editor.getText());
+            this.onSwitch(-1);
+            return;
+        }
+        this.sessionRoot.editor.handleInput?.(data);
+    }
+    invalidate() { this.sessionRoot.invalidate(); }
+    setFocused(focused) { this.sessionRoot.editor.setFocused?.(focused); }
+    dispose() { this.sessionRoot.dispose?.(); }
+}
+function selectedPanel(view) {
+    return view.selectedPanel ?? view.panels[0] ?? null;
+}
+function toOwnedView(workspace, panel, notice, columns, rows) {
+    const agent = workspace.workspace.agents.find(candidate => candidate.id === panel.agentId);
+    return {
+        contractVersion: OWNED_UI_CONTRACT_VERSION,
+        sessionId: panel.sessionId,
+        revision: workspace.workspace.revision + panel.lastSequence,
+        lifecycle: ownedLifecycle(panel.lifecycle),
+        transcript: panel.transcript.flatMap(messageBlocks),
+        editor: {
+            text: panel.editorText,
+            queuedSubmissions: [],
+            selection: null,
+            cursorOffset: panel.editorText.length,
+            historyRevision: panel.lastSequence,
+            submitEnabled: panel.lifecycle !== "stopping" && panel.lifecycle !== "stopped" && panel.lifecycle !== "failed",
+        },
+        status: {
+            title: agent?.displayName ?? panel.agentId,
+            workingMessage: panel.lifecycle === "busy" ? "Working" : null,
+            diagnostics: panel.failure ? [panel.failure] : notice ? [notice] : [],
+            badges: [
+                `${workspace.panels.length} agents`,
+                ...(agent?.unreadActivity ? [`${agent.unreadActivity} unread`] : []),
+                ...(agent?.attention ? ["attention"] : []),
+            ],
+            footer: { branch: null, sessionName: agent?.displayName ?? null, availableProviderCount: 0, extensionStatuses: [] },
+        },
+        terminal: { columns, rows, focusedRegion: "editor", hardwareCursor: true },
+        activeModel: null,
+        thinkingLevel: "medium",
+        activeCommandIds: panel.activeCommandIds,
+        dialog: null,
+        overlay: null,
+        customizations: [],
+        diagnostics: panel.failure ? [{ sequence: panel.lastSequence, code: "structured-agent", severity: "error", message: panel.failure, recoverable: true }] : [],
+    };
+}
+function messageBlocks(message) {
+    return message.content.map((content, index) => {
+        const base = { id: `${message.id}.${index}`, status: message.status === "streaming" ? "live" : "finalized", revision: index + 1, title: null };
+        if (content.kind === "thinking")
+            return { ...base, kind: "thinking", text: content.text, payload: {} };
+        if (content.kind === "tool-call")
+            return { ...base, kind: "tool-call", title: content.toolName, text: JSON.stringify(content.input), payload: content };
+        if (content.kind === "tool-result")
+            return { ...base, kind: "tool-result", text: JSON.stringify(content.output), payload: content };
+        if (content.kind === "image")
+            return { ...base, kind: "custom", title: content.mediaType, text: "[image]", payload: content };
+        if (content.kind === "unknown")
+            return { ...base, kind: "custom", title: content.sourceType, text: JSON.stringify(content.payload), payload: content };
+        return { ...base, kind: message.role === "user" ? "user" : message.role === "system" ? "system" : message.role === "tool" ? "tool-result" : "assistant", text: content.text, payload: {} };
+    });
+}
+function ownedLifecycle(lifecycle) {
+    return lifecycle;
+}
+function truncate(value, width) {
+    if (width <= 0)
+        return "";
+    return value.length <= width ? value : width === 1 ? "…" : `${value.slice(0, width - 1)}…`;
+}

package/dist/src/features/workspace/index.d.ts

@@ -4,3 +4,4 @@ export * from "./reconciliation.js";
 export * from "./reducer.js";
 export * from "./router.js";
 export * from "./store.js";
+export * from "./structured-tabs.js";

package/dist/src/features/workspace/index.js

@@ -4,3 +4,4 @@ export * from "./reconciliation.js";
 export * from "./reducer.js";
 export * from "./router.js";
 export * from "./store.js";
+export * from "./structured-tabs.js";

package/dist/src/features/workspace/router.d.ts

@@ -22,10 +22,15 @@ export declare class WorkspaceRouter {
     constructor(reducer: WorkspaceReducer);
     createAgent(agent: ManagedAgentDescriptor): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     selectAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
+    restartAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
+    markRecovered(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
+    markFailed(agentId: string, code: string, message: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
+    requestAttention(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     stopAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     removeAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     recordActivity(agentId: string, amount?: number): Promise<WorkspaceRouterResult<number>>;
     sendStructuredCommand(agentId: string, command: string, payload: unknown): Promise<WorkspaceRouterResult<RoutedStructuredCommand>>;
     cancelStructuredCommand(agentId: string, targetCorrelationId: string): Promise<WorkspaceRouterResult<StructuredCommandRecord>>;
+    settleStructuredCommand(agentId: string, correlationId: string, outcome: "completed" | "failed"): Promise<WorkspaceRouterResult<StructuredCommandRecord>>;
     view(): WorkspaceView;
 }

package/dist/src/features/workspace/router.js

@@ -23,6 +23,18 @@ export class WorkspaceRouter {
     selectAgent(agentId) {
         return this.#enqueue(() => this.reducer.selectAgent(agentId));
     }
+    restartAgent(agentId) {
+        return this.#enqueue(() => this.reducer.restartAgent(agentId));
+    }
+    markRecovered(agentId) {
+        return this.#enqueue(() => this.reducer.markRecovered(agentId));
+    }
+    markFailed(agentId, code, message) {
+        return this.#enqueue(() => this.reducer.markFailed(agentId, code, message));
+    }
+    requestAttention(agentId) {
+        return this.#enqueue(() => this.reducer.requestAttention(agentId));
+    }
     stopAgent(agentId) {
         return this.#enqueue(() => this.reducer.stopAgent(agentId));
     }
@@ -92,6 +104,20 @@ export class WorkspaceRouter {
             return applied(this.reducer.view(), result.record);
         });
     }
+    settleStructuredCommand(agentId, correlationId, outcome) {
+        return this.#enqueue(() => {
+            const agent = this.reducer.view().agents.find(candidate => candidate.id === agentId);
+            if (!agent)
+                return reject("unknown-agent", `workspace agent does not exist: ${agentId}`);
+            const tracker = this.#trackerFor(agent);
+            if (!tracker)
+                return reject("capability-mismatch", `agent ${agent.id} is not structured`);
+            const result = tracker.complete(correlationId, outcome);
+            if (result.kind === "rejected")
+                return result;
+            return applied(this.reducer.view(), result.record);
+        });
+    }
     view() {
         return this.reducer.view();
     }

package/dist/src/features/workspace/structured-tabs.d.ts

@@ -0,0 +1,83 @@
+import { type AgentCommandOutcome, type AgentEnginePort, type AgentMessage, type AgentSessionLifecycle } from "../../foundation/agent-engine-contracts/index.js";
+import { type WorkspacePresentationModel } from "./presentation.js";
+import { type WorkspaceView } from "./reducer.js";
+import { WorkspaceRouter } from "./router.js";
+export interface StructuredWorkspaceLimits {
+    readonly maxAgents: number;
+    readonly maxMessagesPerAgent: number;
+    readonly maxMessageBytes: number;
+    readonly maxEditorBytes: number;
+}
+export interface StructuredWorkspaceTabsOptions {
+    readonly workspaceId?: string;
+    readonly cwd: string;
+    readonly createEngine: (agentId: string) => Promise<AgentEnginePort>;
+    readonly limits?: Partial<StructuredWorkspaceLimits>;
+    readonly now?: () => string;
+}
+export interface StructuredAgentTabView {
+    readonly role: "tabpanel";
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly selected: boolean;
+    readonly lifecycle: AgentSessionLifecycle;
+    readonly transcript: readonly AgentMessage[];
+    readonly toolMessages: readonly AgentMessage[];
+    readonly editorText: string;
+    readonly activeCommandIds: readonly string[];
+    readonly lastSequence: number;
+    readonly failure: string | null;
+    readonly accessibleDescription: string;
+}
+export interface StructuredWorkspaceTabSelector {
+    readonly role: "tab";
+    readonly agentId: string;
+    readonly label: string;
+    readonly selected: boolean;
+    readonly accessibleDescription: string;
+}
+export interface StructuredWorkspaceTabsView {
+    readonly role: "tablist";
+    readonly workspace: WorkspaceView;
+    readonly presentation: WorkspacePresentationModel;
+    readonly tabs: readonly StructuredWorkspaceTabSelector[];
+    readonly panels: readonly StructuredAgentTabView[];
+    readonly selectedPanel: StructuredAgentTabView | null;
+}
+export type StructuredWorkspaceTabsResult<T> = {
+    readonly kind: "applied";
+    readonly view: StructuredWorkspaceTabsView;
+    readonly value: T;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+    readonly diagnostic: string;
+};
+export declare class StructuredWorkspaceTabs {
+    #private;
+    readonly router: WorkspaceRouter;
+    constructor(options: StructuredWorkspaceTabsOptions);
+    subscribe(listener: (view: StructuredWorkspaceTabsView) => void): () => void;
+    createAgent(input: {
+        readonly id: string;
+        readonly displayName: string;
+        readonly sessionId?: string;
+    }): Promise<StructuredWorkspaceTabsResult<StructuredAgentTabView>>;
+    selectAgent(agentId: string): Promise<StructuredWorkspaceTabsResult<StructuredAgentTabView>>;
+    setEditorText(agentId: string, text: string): StructuredWorkspaceTabsResult<StructuredAgentTabView>;
+    submitSelected(): Promise<StructuredWorkspaceTabsResult<{
+        readonly correlationId: string;
+        readonly outcome: AgentCommandOutcome;
+    }>>;
+    sendPrompt(agentId: string, text: string): Promise<StructuredWorkspaceTabsResult<{
+        readonly correlationId: string;
+        readonly outcome: AgentCommandOutcome;
+    }>>;
+    stopAgent(agentId: string): Promise<StructuredWorkspaceTabsResult<StructuredAgentTabView>>;
+    restartAgent(agentId: string): Promise<StructuredWorkspaceTabsResult<StructuredAgentTabView>>;
+    refreshAgent(agentId: string): Promise<StructuredWorkspaceTabsResult<StructuredAgentTabView>>;
+    removeAgent(agentId: string): Promise<StructuredWorkspaceTabsResult<string>>;
+    flush(): Promise<void>;
+    view(): StructuredWorkspaceTabsView;
+    dispose(): Promise<void>;
+}