@agimon-ai/doompi-author 0.0.1-alpha.10

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@agimon-ai/doompi-author",
+  "version": "0.0.1-alpha.10",
+  "description": "Visual steering workspace for focused document review and bounded authoring",
+  "keywords": [
+    "ai",
+    "authoring",
+    "coding-agent",
+    "developer-tools",
+    "doompi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "typescript"
+  ],
+  "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/doompi/issues"
+  },
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/doompi.git",
+    "directory": "packages/minor/doompi-author"
+  },
+  "files": [
+    "dist",
+    "src/web",
+    "src/types/author.ts",
+    "src/types/webAuthor.ts",
+    "src/types/structuredDocuments.ts",
+    "src/extensions/web.ts",
+    "src/prompts",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "!src/web/**/*.stories.tsx"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "jsnext:main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./extensions/pi": {
+      "types": "./dist/extensions/pi.d.mts",
+      "import": "./dist/extensions/pi.mjs",
+      "require": "./dist/extensions/pi.cjs"
+    },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
+    "./package.json": "./package.json",
+    "./author-facade": {
+      "types": "./dist/authorFacade.d.mts",
+      "import": "./dist/authorFacade.mjs",
+      "require": "./dist/authorFacade.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agimon-ai/doompi-core": "0.0.1-alpha.72",
+    "@agimon-ai/doompi-minor-mode": "0.0.1-alpha.72",
+    "@agimon-ai/doompi-web-components": "0.0.1-alpha.30",
+    "@agimon-ai/doompi-web-security": "0.0.1-alpha.32",
+    "@deepseek-ai/cordis": "4.0.2",
+    "csv-parse": "7.0.2",
+    "hono": "4.13.7",
+    "saxes": "6.0.0",
+    "typebox": "1.3.30",
+    "yauzl": "3.4.0",
+    "yazl": "3.3.1"
+  },
+  "devDependencies": {
+    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.67",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@tanstack/react-store": "0.11.1",
+    "@tanstack/store": "0.11.1",
+    "@types/node": "26.5.1",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/yauzl": "3.4.0",
+    "@types/yazl": "3.3.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "doompiServer": {
+    "entry": "./src/extensions/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "global",
+      "workspace",
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/api-contracts.mjs"
+    }
+  },
+  "doompiWeb": {
+    "pluginId": "author",
+    "channels": [
+      "author_webmcp"
+    ],
+    "client": "./src/extensions/web.ts",
+    "scopes": [
+      "session"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extensions/pi.mjs"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p src/web/tsconfig.json",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt ."
+  }
+}

package/src/extensions/web.ts

@@ -0,0 +1,71 @@
+import { defineWebPlugin, type WebPluginRuntime } from '@agimon-ai/doompi-core/web';
+
+import { startAuthorBrowserBridge } from '../web/api/authorBrowserBridge';
+import { authorFileLinks } from '../web/components/AuthorDocumentPanel';
+import { AuthorPanel } from '../web/components/AuthorPanel';
+import { DescribeAuthorToolsToolCard } from '../web/components/DescribeAuthorToolsToolCard';
+import { OpenAuthoringFileToolCard } from '../web/components/OpenAuthoringFileToolCard';
+import { UseAuthorToolsToolCard } from '../web/components/UseAuthorToolsToolCard';
+import { recordAuthorCaptureStatus, recordAuthorComposerSubmission } from '../web/stores/authorRequestLifecycle';
+import { authorChannel } from '../web/stores/authorStore';
+import { authorWorkspace } from '../web/stores/authorWorkspaceStore';
+
+/**
+ * This package's cockpit presence: the named export the generated plugin
+ * registry imports. Plugins are independent, so nothing here depends on
+ * install order; every relation to another plugin resolves by name.
+ */
+function startAuthor(runtime: WebPluginRuntime): () => void {
+  const stopBridge = startAuthorBrowserBridge(runtime);
+  const stopSubmissions = runtime.onComposerSubmitted?.(recordAuthorComposerSubmission) ?? (() => undefined);
+  const stopCaptureStatus = runtime.onCaptureStatus?.(recordAuthorCaptureStatus) ?? (() => undefined);
+  return () => {
+    stopSubmissions();
+    stopCaptureStatus();
+    stopBridge();
+  };
+}
+
+export const webPlugin = defineWebPlugin({
+  id: 'author',
+  session: {
+    dockFaces: [
+      {
+        id: 'authoring',
+        label: 'authoring',
+        order: 30,
+        autoSelect: true,
+        panel: AuthorPanel,
+        requiredMinorMode: 'author',
+        visibility: {
+          subscribe(listener) {
+            const subscription = authorWorkspace.store.subscribe(listener);
+            return () => subscription.unsubscribe();
+          },
+          isVisible(sessionId) {
+            return sessionId !== null && authorWorkspace.store.state.sessions[sessionId]?.focusedDocument !== undefined;
+          },
+        },
+      },
+    ],
+    minorModes: [{ name: 'author', keys: 'o a', order: 45 }],
+    leaderBindings: [
+      {
+        id: 'author.toggle',
+        path: [
+          { key: 'o', label: 'other', detail: 'optional modes and tools' },
+          { key: 'a', label: 'author', detail: 'enable or disable focused document authoring' },
+        ],
+        command: 'minor author',
+      },
+    ],
+    channels: [authorChannel],
+    fileLinks: authorFileLinks,
+    toolRenderers: [
+      { tools: ['open_authoring_file'], message: OpenAuthoringFileToolCard },
+      { tools: ['describe_author_tools'], message: DescribeAuthorToolsToolCard },
+      { tools: ['use_author_tools'], message: UseAuthorToolsToolCard },
+    ],
+    start: startAuthor,
+  },
+});

package/src/prompts/doompi-use-author/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: doompi-use-author
+description: 'Use @agimon-ai/doompi-author: Visual steering workspace for focused document review and bounded authoring'
+---
+
+# Use Author
+
+Read the package [README](../../../README.md) for its exact installation, command, configuration, and behavior.
+
+## Guidance
+
+- Use `/doom-author` as the package's primary Pi entrypoint.
+- Treat the package README and its linked resources as the source of truth for package-specific behavior.
+- Do not require DoomPi Help for runtime activation. Help only makes this package guidance discoverable while the minor mode is active.
+- Autonomous Voice coordinates are evidence, not mutation authority. Call `author_describe_grid`, then `author_resolve_grid_cell` with the returned geometry token and the user's verbatim instruction.
+- Mutate only through the resulting `regionId` with `author_apply_region`, passing the expected revision and source digest. Apply multi-region requests sequentially and use the revision returned by each successful mutation for the next region. On `STALE_GRID`, `STALE_DOCUMENT`, or `STALE_REGION`, describe and resolve again.
+- Text, Markdown, editable cells, slide text, and image crop support mutation. PDF and video regions are capture-only.

package/src/types/author.ts

@@ -0,0 +1,45 @@
+export const AUTHOR_MODE_ID = 'author' as const;
+export const OPEN_AUTHORING_FILE_TOOL_NAME = 'open_authoring_file' as const;
+
+export type AuthorModeActivation = 'inactive' | 'active';
+
+export interface AuthorModeSnapshot {
+  activation: AuthorModeActivation;
+  catalogToken: string;
+  capabilityCount: number;
+}
+
+export type AuthorJsonSchema = Readonly<Record<string, unknown>>;
+
+export interface AuthorViewportCapabilityDescriptor {
+  name: string;
+  label: string;
+  description: string;
+  inputSchema: AuthorJsonSchema;
+}
+
+export interface AuthorViewportCapability extends AuthorViewportCapabilityDescriptor {
+  execute(argumentsValue: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+}
+
+export interface AuthorViewportCatalogSnapshot {
+  catalogToken: string;
+  tools: AuthorViewportCapabilityDescriptor[];
+}
+
+export interface AuthorOpenFileResult {
+  path: string;
+  byteLength: number;
+}
+
+export interface UseAuthorToolInput {
+  catalogToken: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface AuthorToolResult {
+  catalogToken: string;
+  name: string;
+  result: unknown;
+}

package/src/types/structuredDocuments.ts

@@ -0,0 +1,63 @@
+export type StructuredDocumentFormat = 'markdown-slides' | 'csv' | 'pptx' | 'xlsx';
+
+export interface DocumentManifest {
+  format: StructuredDocumentFormat;
+  sourceDigest: string;
+  byteLength: number;
+  fragmentCount: number;
+  metadata: Record<string, string | number | boolean>;
+}
+
+export interface DocumentFragment {
+  id: string;
+  kind: 'slide' | 'cell' | 'text-run';
+  text: string;
+  readOnly?: boolean;
+  location: string;
+}
+
+export interface DocumentRenderModel {
+  format: StructuredDocumentFormat;
+  blocks: Array<{ id: string; text: string; readOnly: boolean }>;
+}
+
+export interface DocumentOperation {
+  fragmentId: string;
+  replacement: string;
+}
+
+export interface DocumentOperationLogEntry extends DocumentOperation {
+  previous: string;
+}
+
+export interface DocumentPreflightIssue {
+  code: string;
+  message: string;
+  fragmentId?: string;
+}
+
+export interface DocumentPreflightReport {
+  accepted: boolean;
+  digest: string;
+  sourceDigest: string;
+  operations: DocumentOperationLogEntry[];
+  issues: DocumentPreflightIssue[];
+}
+
+export interface ParsedStructuredDocument {
+  manifest: DocumentManifest;
+  fragments: DocumentFragment[];
+  renderModel: DocumentRenderModel;
+}
+
+export interface SerializedStructuredDocument {
+  bytes: Uint8Array;
+  operationLog: DocumentOperationLogEntry[];
+  manifest: DocumentManifest;
+}
+
+export interface CsvDialect {
+  delimiter: ',' | ';' | '\t' | '|';
+  quote: '"' | "'";
+  recordDelimiter: '\n' | '\r\n';
+}

package/src/types/webAuthor.ts

@@ -0,0 +1,85 @@
+import type { AuthorViewportCapabilityDescriptor } from './author';
+
+export const authorChannelType = 'author_webmcp';
+
+export interface AuthorRegisterMessage {
+  kind: 'register';
+  generation: number;
+}
+
+export interface AuthorReleaseMessage {
+  kind: 'release';
+  generation: number;
+}
+export interface AuthorCatalogMessage {
+  kind: 'catalog';
+  generation: number;
+  ownerToken: string;
+  tools: AuthorViewportCapabilityDescriptor[];
+}
+
+export interface AuthorResultMessage {
+  kind: 'result';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+  result: unknown;
+}
+
+export interface AuthorCancelledMessage {
+  kind: 'cancelled';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+}
+
+export type AuthorBrowserMessage =
+  | AuthorRegisterMessage
+  | AuthorReleaseMessage
+  | AuthorCatalogMessage
+  | AuthorResultMessage
+  | AuthorCancelledMessage;
+
+export interface AuthorAcceptedMessage {
+  kind: 'accepted';
+  generation: number;
+  ownerToken: string;
+  catalogToken?: string;
+  leaseMs: number;
+}
+
+export interface AuthorRequestMessage {
+  kind: 'request';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface AuthorCancelMessage {
+  kind: 'cancel';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+}
+
+export interface AuthorRejectedMessage {
+  kind: 'rejected';
+  reason: string;
+}
+
+export type AuthorHubMessage =
+  | AuthorAcceptedMessage
+  | AuthorRequestMessage
+  | AuthorCancelMessage
+  | AuthorRejectedMessage;
+
+export interface AuthorWebView {
+  activation: 'inactive' | 'active';
+  capabilityCount: number;
+}

package/src/web/api/authorBroker.ts

@@ -0,0 +1,14 @@
+import type { ModelContext } from '@agimon-ai/doompi-core/web';
+
+/** Client-side broker transport. Calls always cross Model Context's execution boundary. */
+export class AuthorClientBroker {
+  readonly #modelContext: ModelContext;
+
+  constructor(modelContext: ModelContext) {
+    this.#modelContext = modelContext;
+  }
+
+  execute(name: string, input: unknown, signal: AbortSignal): Promise<unknown> {
+    return this.#modelContext.executeTool(name, JSON.stringify(input), { signal });
+  }
+}

package/src/web/api/authorBrowserBridge.ts

@@ -0,0 +1,229 @@
+import type { WebPluginRuntime } from '@agimon-ai/doompi-core/web';
+import { Store } from '@tanstack/store';
+
+import type { AuthorBrowserMessage, AuthorHubMessage } from '../../types/webAuthor';
+import type { AuthorTrustedProfile } from '../lib/authorViewportTypes';
+import { AuthorRuntime } from './authorRuntime';
+
+interface ActiveViewport {
+  sessionId: string;
+  generation: number;
+  profiles: readonly AuthorTrustedProfile[];
+  release: () => void;
+  ownerToken?: string;
+  catalogToken?: string;
+}
+
+class AuthorBrowserBridge {
+  readonly #host: WebPluginRuntime;
+  readonly #runtime: AuthorRuntime;
+  readonly #pending = new Map<string, AbortController>();
+  #active: ActiveViewport | undefined;
+  #generation = 0;
+  #disposed = false;
+  readonly #releaseConnected: () => void;
+  #leaseTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(host: WebPluginRuntime) {
+    this.#host = host;
+    this.#runtime = new AuthorRuntime(host);
+    this.#releaseConnected = host.onHubConnected(() => {
+      if (this.#active !== undefined) {
+        this.#active.ownerToken = undefined;
+        this.#active.catalogToken = undefined;
+      }
+      this.#register();
+    });
+  }
+
+  async focus(sessionId: string, profiles: readonly AuthorTrustedProfile[]): Promise<() => void> {
+    if (this.#disposed) throw new Error('Author browser bridge is disposed');
+    const generation = ++this.#generation;
+    const release = await this.#runtime.replaceProfiles(profiles);
+    if (this.#disposed || generation !== this.#generation) {
+      release();
+      return () => undefined;
+    }
+    this.#clearActive();
+    this.#active = { sessionId, generation, profiles, release };
+    this.#register();
+    return () => {
+      if (this.#active?.generation !== generation) return;
+      this.#clearActive();
+      this.#generation += 1;
+    };
+  }
+
+  drop(sessionId: string): void {
+    if (this.#active?.sessionId !== sessionId) return;
+    this.#clearActive();
+    this.#generation += 1;
+  }
+
+  apply(sessionId: string, message: AuthorHubMessage): void {
+    const active = this.#active;
+    if (active === undefined || active.sessionId !== sessionId || message.kind === 'rejected') return;
+    if (
+      message.generation !== active.generation ||
+      (message.ownerToken !== active.ownerToken && active.ownerToken !== undefined)
+    )
+      return;
+    if (message.kind === 'accepted') {
+      active.ownerToken = message.ownerToken;
+      clearTimeout(this.#leaseTimer);
+      this.#leaseTimer = setTimeout(() => this.#register(), Math.max(1000, Math.floor(message.leaseMs / 2)));
+      if (message.catalogToken === undefined) this.#sendCatalog(active);
+      else active.catalogToken = message.catalogToken;
+      return;
+    }
+    if (message.catalogToken !== active.catalogToken) return;
+    if (message.kind === 'cancel') {
+      this.#pending.get(message.requestId)?.abort(new Error('Author tool request cancelled'));
+      return;
+    }
+    if (message.kind !== 'request' || this.#pending.has(message.requestId)) return;
+    const controller = new AbortController();
+    this.#pending.set(message.requestId, controller);
+    void this.#runtime
+      .execute(message.name, message.arguments, controller.signal)
+      .then((result) => {
+        if (!this.#current(active, message.requestId, controller)) return;
+        if (controller.signal.aborted) this.#sendCancelled(active, message.requestId);
+        else
+          this.#send(active.sessionId, {
+            kind: 'result',
+            generation: active.generation,
+            ownerToken: active.ownerToken!,
+            catalogToken: active.catalogToken!,
+            requestId: message.requestId,
+            result,
+          });
+      })
+      .catch((error: unknown) => {
+        if (!this.#current(active, message.requestId, controller)) return;
+        if (controller.signal.aborted) this.#sendCancelled(active, message.requestId);
+        else {
+          const messageText = error instanceof Error ? error.message : String(error);
+          const code = /^([A-Z][A-Z_]+):/u.exec(messageText)?.[1] ?? 'AUTHOR_TOOL_ERROR';
+          this.#send(active.sessionId, {
+            kind: 'result',
+            generation: active.generation,
+            ownerToken: active.ownerToken!,
+            catalogToken: active.catalogToken!,
+            requestId: message.requestId,
+            result: { error: { code, message: messageText } },
+          });
+        }
+      })
+      .finally(() => {
+        if (this.#pending.get(message.requestId) === controller) this.#pending.delete(message.requestId);
+      });
+  }
+
+  activeView(sessionId: string): { activation: 'inactive' | 'active'; capabilityCount: number } {
+    const active = this.#active;
+    return active?.sessionId === sessionId && active.catalogToken !== undefined
+      ? {
+          activation: 'active',
+          capabilityCount: active.profiles.reduce((count, profile) => count + profile.tools.length, 0),
+        }
+      : { activation: 'inactive', capabilityCount: 0 };
+  }
+
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    clearTimeout(this.#leaseTimer);
+    this.#releaseConnected();
+    this.#clearActive();
+    this.#runtime.dispose();
+  }
+
+  #register(): void {
+    const active = this.#active;
+    if (active !== undefined) this.#send(active.sessionId, { kind: 'register', generation: active.generation });
+  }
+
+  #sendCatalog(active: ActiveViewport): void {
+    this.#send(active.sessionId, {
+      kind: 'catalog',
+      generation: active.generation,
+      ownerToken: active.ownerToken!,
+      tools: active.profiles.flatMap((profile) =>
+        profile.tools.map((tool) => ({
+          name: tool.name,
+          label: tool.label ?? tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      ),
+    });
+  }
+
+  #sendCancelled(active: ActiveViewport, requestId: string): void {
+    this.#send(active.sessionId, {
+      kind: 'cancelled',
+      generation: active.generation,
+      ownerToken: active.ownerToken!,
+      catalogToken: active.catalogToken!,
+      requestId,
+    });
+  }
+
+  #send(sessionId: string, payload: AuthorBrowserMessage): void {
+    const workspaceId = this.#host.mount?.scope === 'session' ? this.#host.mount.workspaceId : undefined;
+    const mount = workspaceId ? { scope: 'workspace' as const, workspaceId } : { scope: 'global' as const };
+    void this.#host
+      .invokeServerMethod({ mount, service: 'author.bridge', method: 'send', input: { sessionId, message: payload } })
+      .catch(() => undefined);
+  }
+
+  #current(active: ActiveViewport, requestId: string, controller: AbortController): boolean {
+    return this.#active === active && this.#pending.get(requestId) === controller;
+  }
+
+  #clearActive(): void {
+    clearTimeout(this.#leaseTimer);
+    this.#leaseTimer = undefined;
+    const active = this.#active;
+    if (active !== undefined) {
+      this.#send(active.sessionId, { kind: 'release', generation: active.generation });
+      active.release();
+    }
+    this.#active = undefined;
+    for (const controller of this.#pending.values()) controller.abort(new Error('Author viewport changed'));
+    this.#pending.clear();
+  }
+}
+
+const authorBridgeRuntime = new Store<AuthorBrowserBridge | undefined>(undefined);
+
+export function startAuthorBrowserBridge(runtime: WebPluginRuntime): () => void {
+  authorBridgeRuntime.state?.dispose();
+  const next = new AuthorBrowserBridge(runtime);
+  authorBridgeRuntime.setState(() => next);
+  return () => {
+    if (authorBridgeRuntime.state !== next) return;
+    next.dispose();
+    authorBridgeRuntime.setState(() => undefined);
+  };
+}
+
+export async function focusAuthorViewport(
+  sessionId: string,
+  profiles: readonly AuthorTrustedProfile[],
+): Promise<() => void> {
+  return (await authorBridgeRuntime.state?.focus(sessionId, profiles)) ?? (() => undefined);
+}
+
+export function applyAuthorHubMessage(sessionId: string, message: AuthorHubMessage): void {
+  authorBridgeRuntime.state?.apply(sessionId, message);
+}
+
+export function dropAuthorViewportSession(sessionId: string): void {
+  authorBridgeRuntime.state?.drop(sessionId);
+}
+
+export function authorBridgeView(sessionId: string): { activation: 'inactive' | 'active'; capabilityCount: number } {
+  return authorBridgeRuntime.state?.activeView(sessionId) ?? { activation: 'inactive', capabilityCount: 0 };
+}