@loomweaver/cli 0.7.6 → 0.7.7

package/dist/main.mjs

@@ -53,6 +53,32 @@ function ensurePostcssPlugin(existing, amendment) {
     declined: []
   };
 }
+function ensureDependency(manifest2, amendment) {
+  const root = asObject(manifest2) ?? {};
+  const dependencies = asObject(root["dependencies"]);
+  if (dependencies === void 0 && root["dependencies"] !== void 0) {
+    return {
+      value: root,
+      added: [],
+      declined: ['package.json: "dependencies" is not an object']
+    };
+  }
+  const recorded = dependencies?.[amendment.name] ?? asObject(root["devDependencies"])?.[amendment.name];
+  if (recorded !== void 0) {
+    return { value: root, added: [], declined: [] };
+  }
+  const next = { ...dependencies, [amendment.name]: amendment.version };
+  return {
+    value: {
+      ...root,
+      dependencies: Object.fromEntries(
+        Object.entries(next).toSorted(([a], [b]) => a.localeCompare(b))
+      )
+    },
+    added: [`dependencies: ${amendment.name}@${amendment.version}`],
+    declined: []
+  };
+}
 function ensureBuildTarget(target, amendment, projectRoot) {
   const next = { ...asObject(target) };
   const added = [];
@@ -263,6 +289,9 @@ function describeAmendment(amendment) {
   if (amendment.kind === "postcss") {
     return `Write ${amendment.file} beside your package.json, naming ${amendment.plugin}. Without it the stylesheet is read as plain CSS: no utility class is emitted, the workbench renders unstyled, and the build still reports success.`;
   }
+  if (amendment.kind === "package") {
+    return `Add ${amendment.name}@${amendment.version} to your project's dependencies and install it. Without it the generated files import a package that is not there, so the very first build fails.`;
+  }
   if (amendment.kind === "stylesheet-source") {
     return `Add an @source entry for '${amendment.sourceRoot}' to the application's entry stylesheet, resolved from that stylesheet. Without it none of that code's utilities are emitted.`;
   }
@@ -274,7 +303,9 @@ function describeAmendment(amendment) {
   return [
     ...amendment.styles.length > 0 ? [`name ${amendment.styles.join(", ")} in styles`] : [],
     ...amendment.assets.length > 0 ? [
-      `add assets for ${amendment.assets.map((asset) => asset.input).join(", ")} (the shell fetches its own strings at runtime, so without that glob every label in the chrome renders as its raw translation key)`
+      `add assets for ${amendment.assets.map((asset) => asset.input).join(
+        ", "
+      )} (the shell fetches its own strings at runtime, so without that glob every label in the chrome renders as its raw translation key)`
     ] : [],
     ...amendment.serviceWorker ? [
       `set serviceWorker to ${amendment.serviceWorker} in the production configuration (provideShell registers a worker that 404s otherwise)`
@@ -373,6 +404,589 @@ function validateCapabilities(capabilities, known) {
   return findings;
 }
 
+// ../devkit/src/recipes/angular-weaver/agent-panel.ts
+function panelFile(w) {
+  return `import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { EventType, type BaseEvent, type Tool } from '@ag-ui/core';
+import { ${w.propertyName}Agent } from './${w.id}-agent';
+import { askAgent } from './${w.id}-agent-source';
+
+interface Line {
+  readonly kind: 'you' | 'agent' | 'call' | 'result' | 'note';
+  readonly text: string;
+  readonly args?: string;
+  readonly failed?: boolean;
+}
+
+@Component({
+  selector: '${w.prefix}-${w.id}-agent-panel',
+  templateUrl: './${w.id}-agent-panel.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ${w.className}AgentPanel {
+  protected readonly offered = signal<readonly Tool[]>([]);
+
+  protected readonly lines = signal<readonly Line[]>([]);
+
+  protected readonly busy = signal(false);
+
+  private runs = 0;
+
+  constructor() {
+    this.offered.set(${w.propertyName}Agent()?.list() ?? []);
+  }
+
+  protected async ask(name: string): Promise<void> {
+    const tools = ${w.propertyName}Agent();
+    if (!tools || this.busy()) {
+      return;
+    }
+    this.busy.set(true);
+    try {
+      // Ask for the list again, every run. What a plugin may reach changes as plugins load and the
+      // session changes, and a list kept from earlier offers actions that are no longer there.
+      const offered = tools.list();
+      this.offered.set(offered);
+      this.push({ kind: 'you', text: \`Run \${name}\` });
+      this.push({ kind: 'note', text: \`\${offered.length} tool(s) offered right now\` });
+
+      const request = {
+        runId: \`run-\${++this.runs}\`,
+        prompt: name,
+        tools: offered,
+      };
+      for await (const event of askAgent(request)) {
+        this.draw(event);
+        // Every event goes over, unfiltered. The adapter decides which ones matter; a filter here is
+        // how a call ends up half-assembled.
+        const message = await tools.receive(event);
+        if (message) {
+          this.push({
+            kind: 'result',
+            text: message.error ?? message.content,
+            failed: Boolean(message.error),
+          });
+        }
+      }
+      // A run that ends without its closing event leaves a call open; flush() answers it.
+      const last = await tools.flush();
+      if (last) {
+        this.push({
+          kind: 'result',
+          text: last.error ?? last.content,
+          failed: Boolean(last.error),
+        });
+      }
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  private draw(event: BaseEvent): void {
+    const raw = event as unknown as Record<string, unknown>;
+    switch (event.type) {
+      case EventType.TEXT_MESSAGE_START:
+        this.push({ kind: 'agent', text: '' });
+        break;
+      case EventType.TEXT_MESSAGE_CONTENT:
+        this.grow('text', String(raw['delta'] ?? ''));
+        break;
+      case EventType.TOOL_CALL_START:
+        this.push({
+          kind: 'call',
+          text: String(raw['toolCallName'] ?? ''),
+          args: '',
+        });
+        break;
+      case EventType.TOOL_CALL_ARGS:
+        this.grow('args', String(raw['delta'] ?? ''));
+        break;
+      default:
+        break;
+    }
+  }
+
+  private push(line: Line): void {
+    this.lines.update((all) => [...all, line]);
+  }
+
+  private grow(field: 'text' | 'args', delta: string): void {
+    this.lines.update((all) => {
+      const last = all[all.length - 1];
+      return [
+        ...all.slice(0, -1),
+        { ...last, [field]: \`\${last[field] ?? ''}\${delta}\` },
+      ];
+    });
+  }
+}
+`;
+}
+function panelTemplateFile(w) {
+  return `<div class="flex h-full flex-col gap-3">
+  <p
+    class="shrink-0 rounded-md border border-border bg-surface-raised px-3 py-2 text-xs text-content-muted"
+  >
+    This is a stand-in, not an assistant. It speaks the protocol so you can watch the whole path;
+    replace <code class="text-content">${w.id}-agent-source.ts</code> with your own transport.
+  </p>
+
+  <div class="min-h-0 flex-1 overflow-auto">
+    <ul class="flex flex-col gap-2.5">
+      @for (line of lines(); track $index) {
+        @if (line.kind === 'you') {
+          <li class="max-w-full self-end rounded-lg bg-brand-fill px-3 py-2 text-sm text-on-brand">
+            {{ line.text }}
+          </li>
+        } @else if (line.kind === 'agent') {
+          <li
+            class="max-w-full self-start rounded-lg bg-surface-raised px-3 py-2 text-sm text-content"
+          >
+            {{ line.text }}
+          </li>
+        } @else if (line.kind === 'call') {
+          <li
+            class="rounded-md border border-border px-3 py-2 font-mono text-xs break-all text-content-muted"
+          >
+            {{ line.text }}<span class="text-content-faint">({{ line.args }})</span>
+          </li>
+        } @else if (line.kind === 'result') {
+          <li
+            class="px-1 text-xs"
+            [class.text-negative]="line.failed"
+            [class.text-content-muted]="!line.failed"
+          >
+            {{ line.text }}
+          </li>
+        } @else {
+          <li class="px-1 text-xs text-content-faint">{{ line.text }}</li>
+        }
+      } @empty {
+        <li class="px-1 py-6 text-center text-sm text-content-muted">
+          Pick something below and watch the call go through.
+        </li>
+      }
+    </ul>
+  </div>
+
+  <div class="flex shrink-0 flex-col gap-2 border-t border-border pt-3">
+    <span class="px-1 text-xs font-medium text-content-muted">
+      Offered right now ({{ offered().length }})
+    </span>
+    @for (tool of offered(); track tool.name) {
+      <button
+        type="button"
+        class="lw-btn lw-btn--default lw-btn--sm h-auto justify-start py-2 text-left whitespace-normal"
+        [disabled]="busy()"
+        (click)="ask(tool.name)"
+      >
+        {{ tool.description }}
+      </button>
+    } @empty {
+      <span class="px-1 text-xs text-content-faint">
+        Nothing is offered. A command reaches this list only when it is registered with
+        <code class="text-content">callable: true</code>, and reaching another plugin's commands
+        needs the <code class="text-content">automation</code> capability granted.
+      </span>
+    }
+  </div>
+</div>
+`;
+}
+
+// ../devkit/src/recipes/angular-weaver/agent-stand-in.ts
+function standInFile(w) {
+  return `import { EventType, type BaseEvent, type Tool } from '@ag-ui/core';
+
+// WHAT THIS IS: a stand-in for an agent, and not an agent. It speaks the AG-UI protocol and nothing
+// else \u2014 no model, no network, no judgement \u2014 so that the whole path from the offered tools through
+// a call to its outcome runs on the first serve, before you have connected anything.
+//
+// WHAT REPLACES IT: this file, and only this file. Point askAgent at your own endpoint and yield the
+// events it streams back. The panel and the connection beside it stay exactly as they are.
+
+const PACE = 40;
+
+export interface AgentRequest {
+  readonly runId: string;
+  readonly prompt: string;
+  /** What the workbench offers right now \u2014 the same list a real agent would be handed. */
+  readonly tools: readonly Tool[];
+}
+
+export async function* askAgent(
+  request: AgentRequest,
+): AsyncGenerator<BaseEvent> {
+  const picked = request.tools.find((tool) =>
+    request.prompt.includes(tool.name),
+  );
+
+  yield event(EventType.RUN_STARTED, {
+    threadId: '${w.id}-stand-in',
+    runId: request.runId,
+  });
+  yield* speak(
+    \`\${request.runId}.says\`,
+    picked
+      ? \`You asked for "\${request.prompt}". I can see \${request.tools.length} tool(s) and \${picked.name} is one of them, so I will call it.\`
+      : \`You asked for "\${request.prompt}", and nothing among the \${request.tools.length} tool(s) I was offered matches it, so I will not call anything.\`,
+  );
+
+  if (picked) {
+    const toolCallId = \`\${request.runId}.call\`;
+    yield event(EventType.TOOL_CALL_START, {
+      toolCallId,
+      toolCallName: picked.name,
+    });
+    // Arguments arrive in pieces, exactly as they do from a real model. The adapter assembles them;
+    // nothing downstream ever sees a half-written call. A real agent fills them from the JSON Schema
+    // the workbench described in picked.parameters; a stand-in has nothing to fill them from, so it
+    // sends none and lets the command apply its own defaults.
+    for (const piece of chunks(JSON.stringify({}), 4)) {
+      yield event(EventType.TOOL_CALL_ARGS, { toolCallId, delta: piece });
+      await pause();
+    }
+    yield event(EventType.TOOL_CALL_END, { toolCallId });
+  }
+
+  yield event(EventType.RUN_FINISHED, {
+    threadId: '${w.id}-stand-in',
+    runId: request.runId,
+  });
+}
+
+async function* speak(
+  messageId: string,
+  text: string,
+): AsyncGenerator<BaseEvent> {
+  yield event(EventType.TEXT_MESSAGE_START, { messageId, role: 'assistant' });
+  for (const piece of chunks(text, 10)) {
+    yield event(EventType.TEXT_MESSAGE_CONTENT, { messageId, delta: piece });
+    await pause();
+  }
+  yield event(EventType.TEXT_MESSAGE_END, { messageId });
+}
+
+function chunks(text: string, size: number): readonly string[] {
+  const pieces: string[] = [];
+  for (let at = 0; at < text.length; at += size) {
+    pieces.push(text.slice(at, at + size));
+  }
+  return pieces;
+}
+
+function event(type: EventType, fields: Record<string, unknown>): BaseEvent {
+  return { type, ...fields } as unknown as BaseEvent;
+}
+
+function pause(): Promise<void> {
+  return new Promise((done) => setTimeout(done, PACE));
+}
+`;
+}
+
+// ../devkit/src/recipes/angular-weaver/agent-files.ts
+var AG_UI_ADAPTER_VERSION = "0.7.7";
+var AG_UI_PROTOCOL_VERSION = "0.0.x";
+function connectionFile(w) {
+  return `import { signal } from '@angular/core';
+import {
+  commandTools,
+  type CommandTools,
+  type PendingToolCall,
+  type ToolDecision,
+} from '@loomweaver/ag-ui';
+import type { PluginContext } from '@loomweaver/plugin-sdk';
+
+// Commands an agent may not run on its own word. Each one asks the person at the keyboard first, and
+// declining stops it: the workbench never sees the call. This weaver's own command is listed as an
+// example \u2014 replace it with the ones that actually cost something.
+const CONSEQUENTIAL = new Set(['${w.id}.hello']);
+
+// A factory, not a module-level connection: everything a run needs lives in the closure, so a second
+// one never shares state with the first.
+export function ${w.propertyName}Connection(ctx: PluginContext): CommandTools {
+  return commandTools(ctx, { before: (call) => decide(ctx, call) });
+}
+
+// The one connection this plugin activates, published for its panel. Set in activate(), cleared in
+// deactivate(), so the panel renders an honest empty state either side of that.
+export const ${w.propertyName}Agent = signal<CommandTools | null>(null);
+
+async function decide(
+  ctx: PluginContext,
+  call: PendingToolCall,
+): Promise<ToolDecision> {
+  if (!CONSEQUENTIAL.has(call.commandId)) {
+    return { decision: 'run' };
+  }
+  const yes = await ctx.ui.confirm({
+    title: '${w.id}.agent.confirm.title',
+    message: '${w.id}.agent.confirm.message',
+    confirmLabel: '${w.id}.agent.confirm.yes',
+    cancelLabel: '${w.id}.agent.confirm.no',
+    tone: 'warning',
+  });
+  // A decision can only narrow. Letting a call through does not make it reachable: the workbench
+  // still refuses whatever it always refused.
+  return yes
+    ? { decision: 'run' }
+    : { decision: 'decline', reason: 'the person at the keyboard said no.' };
+}
+`;
+}
+function specFile(w) {
+  return `import { EventType, type BaseEvent } from '@ag-ui/core';
+import type { CommandArguments, PluginContext } from '@loomweaver/plugin-sdk';
+import { ${w.propertyName}Connection } from './${w.id}-agent';
+
+interface Asked {
+  readonly id: string;
+  readonly args?: CommandArguments;
+}
+
+function contextThat(confirms: boolean, ran: Asked[]): PluginContext {
+  return {
+    invocableCommands: () => [
+      { id: '${w.id}.hello', title: '${w.name} action', description: 'Shows a short message.' },
+    ],
+    invokeCommand: (id: string, args?: CommandArguments) => {
+      ran.push({ id, args });
+      return Promise.resolve({ outcome: 'answered', value: 'it ran' });
+    },
+    ui: { confirm: () => Promise.resolve(confirms) },
+  } as unknown as PluginContext;
+}
+
+function event(type: EventType, fields: Record<string, unknown>): BaseEvent {
+  return { type, ...fields } as unknown as BaseEvent;
+}
+
+describe('${w.propertyName}Connection', () => {
+  it('offers what the workbench offers', () => {
+    const tools = ${w.propertyName}Connection(contextThat(true, []));
+    expect(tools.list().map((tool) => tool.name)).toEqual(['${w.id}.hello']);
+  });
+
+  it('assembles a call from its events and answers with the outcome', async () => {
+    const ran: Asked[] = [];
+    const tools = ${w.propertyName}Connection(contextThat(true, ran));
+
+    expect(
+      await tools.receive(
+        event(EventType.TOOL_CALL_START, {
+          toolCallId: 'c1',
+          toolCallName: '${w.id}.hello',
+        }),
+      ),
+    ).toBeNull();
+    await tools.receive(
+      event(EventType.TOOL_CALL_ARGS, { toolCallId: 'c1', delta: '{"who"' }),
+    );
+    await tools.receive(
+      event(EventType.TOOL_CALL_ARGS, { toolCallId: 'c1', delta: ':"you"}' }),
+    );
+    const answer = await tools.receive(
+      event(EventType.TOOL_CALL_END, { toolCallId: 'c1' }),
+    );
+
+    expect(ran).toEqual([{ id: '${w.id}.hello', args: { who: 'you' } }]);
+    expect(answer?.content).toBe('it ran');
+    expect(answer?.error).toBeUndefined();
+  });
+
+  it('never reaches the workbench when a consequential call is declined', async () => {
+    const ran: Asked[] = [];
+    const tools = ${w.propertyName}Connection(contextThat(false, ran));
+
+    await tools.receive(
+      event(EventType.TOOL_CALL_START, {
+        toolCallId: 'c2',
+        toolCallName: '${w.id}.hello',
+      }),
+    );
+    await tools.receive(
+      event(EventType.TOOL_CALL_ARGS, { toolCallId: 'c2', delta: '{}' }),
+    );
+    const answer = await tools.receive(
+      event(EventType.TOOL_CALL_END, { toolCallId: 'c2' }),
+    );
+
+    expect(ran).toEqual([]);
+    expect(answer?.error).toContain('did not run');
+  });
+});
+`;
+}
+function agentSurfaceBlock(w) {
+  return [
+    "    ctx.registerSurface({",
+    `      id: '${w.id}.agent',`,
+    `      title: '${w.id}.agent.title',`,
+    `      icon: '${w.id}',`,
+    "      docks: ['right-panel'],",
+    `      component: ${w.className}AgentPanel,`,
+    "    });"
+  ].join("\n");
+}
+function agentFiles(w) {
+  const files = {
+    [`src/lib/agent/${w.id}-agent.ts`]: connectionFile(w),
+    [`src/lib/agent/${w.id}-agent-source.ts`]: standInFile(w),
+    [`src/lib/agent/${w.id}-agent-panel.ts`]: panelFile(w),
+    [`src/lib/agent/${w.id}-agent-panel.html`]: panelTemplateFile(w)
+  };
+  if (w.features.spec) {
+    files[`src/lib/agent/${w.id}-agent.spec.ts`] = specFile(w);
+  }
+  return files;
+}
+
+// ../devkit/src/recipes/angular-weaver/weaver-terms.ts
+var CONTAINER_EXAMPLE_ID = "example";
+function capabilityItems(capabilities) {
+  return capabilities.map((capability) => `'${capability}'`).join(", ");
+}
+
+// ../devkit/src/recipes/angular-weaver/weaver-readme.ts
+function surfaceNotes(w) {
+  const railNote = "Rail and bar items reference region ids (`primary`, `status`) that must exist in your layout.";
+  if (w.features.container) {
+    return [
+      `The surface is a **container**: it is routable at \`/${w.id}/:id\`, and its tab holds a`,
+      "nested pane tree of child surfaces. The host draws the inner tabs, splits and drag targets; this",
+      "weaver only declares which children it offers.",
+      "",
+      `- \`children\` is what the inner "new tab" picker lists \u2014 the host access-gates it for you.`,
+      "- `initial` is what a freshly opened container tab starts with.",
+      `- The children declare \`docks: []\`. That is the container-only convention: they are never seeded`,
+      "  into a sidebar, they exist solely inside this container.",
+      `- Each child reads the container's \`:id\` from an injected \`ActivatedRoute\` \u2014 the host supplies a`,
+      "  synthetic one, so a child needs no knowledge of where it is mounted. Two open container tabs are",
+      "  two independent trees, each scoped to its own id.",
+      `- The inner tree is **sealed**: a child cannot be dragged out, and nothing can be dragged in. It`,
+      "  travels with the tab, including into a sidebar or a pop-out window.",
+      "",
+      `The rail item opens the fixed id \`${CONTAINER_EXAMPLE_ID}\`. Replace that with whatever the user`,
+      "actually picked \u2014 a document, a run, a project.",
+      "",
+      railNote
+    ];
+  }
+  if (w.features.instanceable) {
+    return [
+      `The surface is **docked** into the \`primary\` region and marked \`instanceable\`, so the host shows a`,
+      "switcher for saving, naming, renaming and deleting several configurations of it, each with its own",
+      "`VIEW_STATE` blob.",
+      "",
+      "It is deliberately **not** routable. Named instances exist only for a docked surface \u2014 a routable",
+      "one holds the URL pane instead, and the host drops `instanceable` on that path. The rail item",
+      "therefore reveals the surface (`ctx.revealSurface`) rather than navigating to a URL, which focuses",
+      "it wherever the user has since moved it.",
+      "",
+      "The generated view already uses that blob for its sort order, because a hidden surface is destroyed",
+      "as soon as it is clean: state kept in a component field survives neither a tab switch nor",
+      "a collapsed sidebar, and never survived a reload. The rule is *evictable = reload-safe* \u2014 anything",
+      "that must not be lost goes through `VIEW_STATE`, and `set()` replaces the whole blob, so spread it.",
+      "",
+      railNote
+    ];
+  }
+  return [
+    `The surface is routable at \`/${w.id}\`; ${railNote.charAt(0).toLowerCase()}${railNote.slice(1)}`,
+    "",
+    "A routable surface has **no `VIEW_STATE` handle** \u2014 injecting the token there throws. It owns a URL,",
+    "so anything shareable (a filter, the active sub-tab) belongs in route params or `subRoutes`, where it",
+    "survives a deep link too; unsaved edits are `DirtySurface`, and an instance that is expensive to",
+    "rebuild declares `retain: 'always'`. Generate with `--instanceable` for the docked, `VIEW_STATE`",
+    "flavour instead."
+  ];
+}
+function agentNotes(w) {
+  return [
+    "",
+    "## The agent connection",
+    "",
+    `\`src/lib/agent/\` holds three files and one of them is meant to be thrown away.`,
+    "",
+    `- \`${w.id}-agent.ts\` is the connection: the workbench's own commands offered as tools, and a`,
+    "  seam where this weaver decides about a call before it runs. Nothing is registered twice \u2014 the",
+    "  list comes from the workbench, already narrowed by everything that would refuse the call.",
+    `- \`${w.id}-agent-panel.ts\` shows what is offered, the call as it streams, and the outcome.`,
+    `- \`${w.id}-agent-source.ts\` is a **stand-in**, not an assistant: it produces the protocol's own`,
+    "  events so the whole path runs before you have connected anything. Replace that one file with",
+    "  your transport and nothing else changes. No transport, credential or model is generated for",
+    "  you, because none of them can be guessed.",
+    "",
+    "Three things are easy to get wrong and invisible when they are, so the generated code does them",
+    "rather than explaining them: the offered list is asked for again every run, every event is handed",
+    "over unfiltered, and a decision before a call can only narrow what the workbench would have",
+    "allowed anyway.",
+    "",
+    `The generated weaver needs two packages your project may not carry yet:`,
+    "",
+    "```bash",
+    `npm i @loomweaver/ag-ui @ag-ui/core`,
+    "```",
+    "",
+    "The Nx generator and the CLI record them for you; the MCP route names them instead."
+  ];
+}
+function readmeFile(w) {
+  return [
+    `# ${w.name} weaver`,
+    "",
+    `A LoomWeaver weaver (a domain plugin bundle). It consumes only the public \`@loomweaver/plugin-sdk\` contract.`,
+    "",
+    "## Wire it into a distribution",
+    "",
+    `1. Add the plugin to \`providePlugins\` in \`src/app/app.config.ts\`. It is **variadic** and`,
+    `   returns an array, so spread it:`,
+    "",
+    "   ```ts",
+    `   import { ${w.propertyName}Plugin } from '${w.importPath}';   // Nx: the workspace alias; without one, a relative path to this library's src/index.ts`,
+    `   ...providePlugins(${w.propertyName}Plugin),`,
+    "   ```",
+    "",
+    `2. Grant its capabilities (default-deny) via \`provideCapabilityGrants\`:`,
+    "",
+    "   ```ts",
+    `   provideCapabilityGrants({ '${w.id}': [${capabilityItems(w.capabilities)}] });`,
+    "   ```",
+    "",
+    `3. Compose its translations with \`provideTranslationNamespaces('${w.id}')\` \u2014 and serve the`,
+    `   bundle by adding an assets glob to your application's build target, so the loader can fetch`,
+    `   \`/i18n/${w.id}/<lang>.json\` (the Nx generator adds this glob for you):`,
+    "",
+    "   ```json",
+    `   { "glob": "**/*.json", "input": "<path to this library>/src/lib/i18n", "output": "i18n/${w.id}" }`,
+    "   ```",
+    "",
+    `4. If your application compiles the shell's theme with Tailwind, name this library as a source`,
+    `   for it, so the utility classes in these templates are emitted. Tailwind also detects sources`,
+    `   by itself, but that depends on where it resolves the project root and on \`.gitignore\`, and`,
+    `   what the scaffold names covers the application alone (the Nx generator adds this line for`,
+    `   you). Applications scaffolded with \`--styles precompiled\` run no Tailwind and need nothing:`,
+    "",
+    "   ```css",
+    `   @source '<path from that stylesheet to this library>/src';`,
+    "   ```",
+    "",
+    ...surfaceNotes(w),
+    ...w.features.agent ? agentNotes(w) : [],
+    "",
+    "## After scaffolding",
+    "",
+    "- `src/lib/i18n/de.json` starts as a copy of the English strings \u2014 translate it.",
+    `- A scaffolded command defaults its shortcut to \`mod+shift+<first letter of the id>\` \u2014 two weavers whose ids share a first letter collide; pass \`--shortcut\` or edit the command.`,
+    "- The project is generated **untagged**: Nx tags belong to your `depConstraints`, and inventing",
+    "  one would fail a lint policy you never opted this project into. If your workspace enforces",
+    "  module boundaries, give it tags your constraints allow \u2014 `--tags` at generation time, or",
+    "  `tags` in `project.json` afterwards.",
+    ""
+  ].join("\n");
+}
+
 // ../devkit/src/recipes/angular-weaver/weaver-i18n.ts
 function i18nBundle(w) {
   const bundle = { title: w.name };
@@ -385,6 +999,17 @@ function i18nBundle(w) {
     bundle["actionDescription"] = `Shows a short ${w.name} message.`;
   }
   if (w.features.about) bundle["about"] = `About ${w.name}`;
+  if (w.features.agent) {
+    bundle["agent"] = {
+      title: `${w.name} assistant`,
+      confirm: {
+        title: "Run this command?",
+        message: "An agent asked to run a command that was marked consequential.",
+        yes: "Run it",
+        no: "Not now"
+      }
+    };
+  }
   if (w.features.settings)
     bundle["settings"] = { title: w.name, enabled: "Enabled", note: "Note" };
   return bundle;
@@ -428,9 +1053,7 @@ var PLATFORM_BOUND_CHORD_TOKENS = /* @__PURE__ */ new Set([
 ]);
 function assertPlatformNeutralChord(shortcut) {
   const tokens = shortcut.toLowerCase().split("+").map((token) => token.trim());
-  const bound = tokens.find(
-    (token) => PLATFORM_BOUND_CHORD_TOKENS.has(token)
-  );
+  const bound = tokens.find((token) => PLATFORM_BOUND_CHORD_TOKENS.has(token));
   if (bound) {
     throw new Error(
       `Shortcut "${shortcut}" binds the platform-specific "${bound}" key. Use the neutral 'mod' token (e.g. 'mod+shift+k') \u2014 the host renders it as \u2318 on macOS and Ctrl elsewhere.`
@@ -451,8 +1074,9 @@ function resolveFeatures(id, input) {
       'A surface cannot be both a container and instanceable: a container tab holds its own ":id" and is therefore routable, while named instances exist only for a docked, non-routable surface. Pick one.'
     );
   }
+  const agent = Boolean(input?.agent);
   return {
-    command: Boolean(input?.command) || menuSlot !== void 0 || barItem || hasShortcut,
+    command: Boolean(input?.command) || menuSlot !== void 0 || barItem || hasShortcut || agent,
     menuSlot,
     settings: Boolean(input?.settings),
     access: input?.access ? accessLiteral(input.access) : void 0,
@@ -461,6 +1085,7 @@ function resolveFeatures(id, input) {
     about: Boolean(input?.about),
     instanceable,
     container,
+    agent,
     spec: input?.spec !== false
   };
 }
@@ -471,6 +1096,10 @@ function deriveCapabilities(features) {
     set.add("ui");
     set.add("host");
   }
+  if (features.agent) {
+    set.add("ui");
+    set.add("automation");
+  }
   return KNOWN_CAPABILITIES.filter((capability) => set.has(capability));
 }
 function resolveWeaverInput(input) {
@@ -492,10 +1121,6 @@ function resolveWeaverInput(input) {
     importPath: input.importPath?.trim() || `@loomweaver/${input.id}-weaver`
   };
 }
-function capabilityItems(capabilities) {
-  return capabilities.map((capability) => `'${capability}'`).join(", ");
-}
-var CONTAINER_EXAMPLE_ID = "example";
 function containerChildIds(w) {
   return [`${w.id}.canvas`, `${w.id}.details`];
 }
@@ -659,6 +1284,12 @@ function pluginFile(w) {
       `import { ${w.className}AboutDialog } from '../dialogs/${w.id}-about-dialog';`
     );
   }
+  if (w.features.agent) {
+    imports.push(
+      `import { ${w.propertyName}Agent, ${w.propertyName}Connection } from '../agent/${w.id}-agent';`,
+      `import { ${w.className}AgentPanel } from '../agent/${w.id}-agent-panel';`
+    );
+  }
   if (w.features.settings) {
     imports.unshift("import { signal } from '@angular/core';");
   }
@@ -671,6 +1302,11 @@ function pluginFile(w) {
     );
   }
   const body = [`    ctx.contributeIcons({ '${w.id}': icon });`];
+  if (w.features.agent) {
+    body.push(
+      `    ${w.propertyName}Agent.set(${w.propertyName}Connection(ctx));`
+    );
+  }
   if (w.features.command) body.push(commandBlock(w));
   if (w.features.about) body.push(aboutCommandBlock(w));
   body.push(surfaceBlock(w), railBlock(w));
@@ -678,6 +1314,11 @@ function pluginFile(w) {
   if (w.features.barItem) body.push(barItemBlock(w));
   if (w.features.menuSlot) body.push(menuBlock(w));
   if (w.features.settings) body.push(settingsBlock(w));
+  if (w.features.agent) body.push(agentSurfaceBlock(w));
+  const deactivate = w.features.agent ? `
+  deactivate() {
+    ${w.propertyName}Agent.set(null);
+  },` : "";
   return `${imports.join("\n")}
 
 ${consts.join("\n")}
@@ -690,7 +1331,7 @@ export const ${w.propertyName}Plugin: Plugin = {
   },
   activate(ctx) {
 ${body.join("\n")}
-  },
+  },${deactivate}
 };
 `;
 }
@@ -806,7 +1447,7 @@ function childViewTemplateFile(w, heading) {
 </div>
 `;
 }
-function specFile(w) {
+function specFile2(w) {
   return `import { ${w.propertyName}Plugin } from './${w.id}.plugin';
 
 describe('${w.propertyName}Plugin', () => {
@@ -817,112 +1458,6 @@ describe('${w.propertyName}Plugin', () => {
 });
 `;
 }
-function surfaceNotes(w) {
-  const railNote = "Rail and bar items reference region ids (`primary`, `status`) that must exist in your layout.";
-  if (w.features.container) {
-    return [
-      `The surface is a **container**: it is routable at \`/${w.id}/:id\`, and its tab holds a`,
-      "nested pane tree of child surfaces. The host draws the inner tabs, splits and drag targets; this",
-      "weaver only declares which children it offers.",
-      "",
-      `- \`children\` is what the inner "new tab" picker lists \u2014 the host access-gates it for you.`,
-      "- `initial` is what a freshly opened container tab starts with.",
-      `- The children declare \`docks: []\`. That is the container-only convention: they are never seeded`,
-      "  into a sidebar, they exist solely inside this container.",
-      `- Each child reads the container's \`:id\` from an injected \`ActivatedRoute\` \u2014 the host supplies a`,
-      "  synthetic one, so a child needs no knowledge of where it is mounted. Two open container tabs are",
-      "  two independent trees, each scoped to its own id.",
-      `- The inner tree is **sealed**: a child cannot be dragged out, and nothing can be dragged in. It`,
-      "  travels with the tab, including into a sidebar or a pop-out window.",
-      "",
-      `The rail item opens the fixed id \`${CONTAINER_EXAMPLE_ID}\`. Replace that with whatever the user`,
-      "actually picked \u2014 a document, a run, a project.",
-      "",
-      railNote
-    ];
-  }
-  if (w.features.instanceable) {
-    return [
-      `The surface is **docked** into the \`primary\` region and marked \`instanceable\`, so the host shows a`,
-      "switcher for saving, naming, renaming and deleting several configurations of it, each with its own",
-      "`VIEW_STATE` blob.",
-      "",
-      "It is deliberately **not** routable. Named instances exist only for a docked surface \u2014 a routable",
-      "one holds the URL pane instead, and the host drops `instanceable` on that path. The rail item",
-      "therefore reveals the surface (`ctx.revealSurface`) rather than navigating to a URL, which focuses",
-      "it wherever the user has since moved it.",
-      "",
-      "The generated view already uses that blob for its sort order, because a hidden surface is destroyed",
-      "as soon as it is clean: state kept in a component field survives neither a tab switch nor",
-      "a collapsed sidebar, and never survived a reload. The rule is *evictable = reload-safe* \u2014 anything",
-      "that must not be lost goes through `VIEW_STATE`, and `set()` replaces the whole blob, so spread it.",
-      "",
-      railNote
-    ];
-  }
-  return [
-    `The surface is routable at \`/${w.id}\`; ${railNote.charAt(0).toLowerCase()}${railNote.slice(1)}`,
-    "",
-    "A routable surface has **no `VIEW_STATE` handle** \u2014 injecting the token there throws. It owns a URL,",
-    "so anything shareable (a filter, the active sub-tab) belongs in route params or `subRoutes`, where it",
-    "survives a deep link too; unsaved edits are `DirtySurface`, and an instance that is expensive to",
-    "rebuild declares `retain: 'always'`. Generate with `--instanceable` for the docked, `VIEW_STATE`",
-    "flavour instead."
-  ];
-}
-function readmeFile(w) {
-  return [
-    `# ${w.name} weaver`,
-    "",
-    `A LoomWeaver weaver (a domain plugin bundle). It consumes only the public \`@loomweaver/plugin-sdk\` contract.`,
-    "",
-    "## Wire it into a distribution",
-    "",
-    `1. Add the plugin to \`providePlugins\` in \`src/app/app.config.ts\`. It is **variadic** and`,
-    `   returns an array, so spread it:`,
-    "",
-    "   ```ts",
-    `   import { ${w.propertyName}Plugin } from '${w.importPath}';   // Nx: the workspace alias; without one, a relative path to this library's src/index.ts`,
-    `   ...providePlugins(${w.propertyName}Plugin),`,
-    "   ```",
-    "",
-    `2. Grant its capabilities (default-deny) via \`provideCapabilityGrants\`:`,
-    "",
-    "   ```ts",
-    `   provideCapabilityGrants({ '${w.id}': [${capabilityItems(w.capabilities)}] });`,
-    "   ```",
-    "",
-    `3. Compose its translations with \`provideTranslationNamespaces('${w.id}')\` \u2014 and serve the`,
-    `   bundle by adding an assets glob to your application's build target, so the loader can fetch`,
-    `   \`/i18n/${w.id}/<lang>.json\` (the Nx generator adds this glob for you):`,
-    "",
-    "   ```json",
-    `   { "glob": "**/*.json", "input": "<path to this library>/src/lib/i18n", "output": "i18n/${w.id}" }`,
-    "   ```",
-    "",
-    `4. If your application compiles the shell's theme with Tailwind, name this library as a source`,
-    `   for it, so the utility classes in these templates are emitted. Tailwind also detects sources`,
-    `   by itself, but that depends on where it resolves the project root and on \`.gitignore\`, and`,
-    `   what the scaffold names covers the application alone (the Nx generator adds this line for`,
-    `   you). Applications scaffolded with \`--styles precompiled\` run no Tailwind and need nothing:`,
-    "",
-    "   ```css",
-    `   @source '<path from that stylesheet to this library>/src';`,
-    "   ```",
-    "",
-    ...surfaceNotes(w),
-    "",
-    "## After scaffolding",
-    "",
-    "- `src/lib/i18n/de.json` starts as a copy of the English strings \u2014 translate it.",
-    `- A scaffolded command defaults its shortcut to \`mod+shift+<first letter of the id>\` \u2014 two weavers whose ids share a first letter collide; pass \`--shortcut\` or edit the command.`,
-    "- The project is generated **untagged**: Nx tags belong to your `depConstraints`, and inventing",
-    "  one would fail a lint policy you never opted this project into. If your workspace enforces",
-    "  module boundaries, give it tags your constraints allow \u2014 `--tags` at generation time, or",
-    "  `tags` in `project.json` afterwards.",
-    ""
-  ].join("\n");
-}
 var angularWeaver = {
   id: "angular-weaver",
   build(input) {
@@ -961,8 +1496,11 @@ var angularWeaver = {
       files[`src/lib/dialogs/${w.id}-about-dialog.ts`] = aboutDialogFile(w);
       files[`src/lib/dialogs/${w.id}-about-dialog.html`] = aboutDialogTemplateFile(w);
     }
+    if (w.features.agent) {
+      Object.assign(files, agentFiles(w));
+    }
     if (w.features.spec) {
-      files[`src/lib/plugin/${w.id}.plugin.spec.ts`] = specFile(w);
+      files[`src/lib/plugin/${w.id}.plugin.spec.ts`] = specFile2(w);
     }
     return files;
   }
@@ -1892,11 +2430,24 @@ var layout = {
 // ../devkit/src/recipes/angular-weaver/amendments.ts
 function weaverAmendments(input, where) {
   const w = resolveWeaverInput(input);
+  const packages = w.features.agent ? [
+    {
+      kind: "package",
+      name: "@loomweaver/ag-ui",
+      version: `^${AG_UI_ADAPTER_VERSION}`
+    },
+    {
+      kind: "package",
+      name: "@ag-ui/core",
+      version: AG_UI_PROTOCOL_VERSION
+    }
+  ] : [];
   const directory = normalizeProjectRoot(where ?? "");
   if (!directory) {
-    return [];
+    return packages;
   }
   return [
+    ...packages,
     {
       kind: "build-target",
       styles: [],
@@ -1936,6 +2487,7 @@ function weaverInput(values) {
       about: bool(values, "about"),
       instanceable: bool(values, "instanceable"),
       container: bool(values, "container"),
+      agent: bool(values, "agent"),
       access: str(values, "access"),
       spec: bool(values, "spec")
     }
@@ -2062,6 +2614,12 @@ var SCAFFOLDS = [
         description: "Make the surface a container: a routable tab at '<id>/:id' holding a nested pane tree of child surfaces, which the host draws. Not combinable with --instanceable.",
         default: false
       },
+      {
+        name: "agent",
+        type: "boolean",
+        description: "Also scaffold the connection that lets an AG-UI agent run the commands this workbench offers: a docked panel, the seam where a call is decided before it runs, and a local stand-in that speaks the protocol so the whole path works on the first serve. Implies --command.",
+        default: false
+      },
       {
         name: "access",
         type: "string",
@@ -2734,13 +3292,16 @@ var Amender = class {
   planned = [];
   remaining = [];
   configAdded = [];
+  manifestAdded = [];
   config;
+  manifest;
   project;
   plan(amendments2) {
     for (const amendment of amendments2) {
       this.planOne(amendment);
     }
     this.flushConfig();
+    this.flushManifest();
     return { amendments: this.planned, remaining: this.remaining };
   }
   planOne(amendment) {
@@ -2748,6 +3309,10 @@ var Amender = class {
       this.planPostcss(amendment);
       return;
     }
+    if (amendment.kind === "package") {
+      this.planPackage(amendment);
+      return;
+    }
     if (this.workspace.kind !== "angular") {
       this.remaining.push(this.nonAngularNote(amendment));
       return;
@@ -2791,6 +3356,39 @@ var Amender = class {
 `
     });
   }
+  planPackage(amendment) {
+    const file = resolve2(this.workspace.root, "package.json");
+    if (!existsSync2(file)) {
+      this.remaining.push(describeAmendment(amendment));
+      return;
+    }
+    const manifest2 = this.manifest ?? readJsonFile(file);
+    const result = ensureDependency(manifest2, amendment);
+    this.remaining.push(...result.declined);
+    if (result.added.length === 0) {
+      return;
+    }
+    this.manifest = result.value;
+    this.manifestAdded.push(...result.added);
+  }
+  flushManifest() {
+    if (this.manifestAdded.length === 0 || !this.manifest) {
+      return;
+    }
+    const file = resolve2(this.workspace.root, "package.json");
+    this.planned.push({
+      file,
+      display: this.displayName(file),
+      added: this.manifestAdded,
+      content: `${JSON.stringify(this.manifest, null, 2)}
+`
+    });
+    this.remaining.push(
+      `Install what was just recorded in ${this.displayName(file)} (${this.manifestAdded.map((entry) => entry.replace("dependencies: ", "")).join(
+        ", "
+      )}) \u2014 recording it is not installing it, and the build fails until you do.`
+    );
+  }
   planBuildTarget(amendment, project) {
     const target = this.buildTarget(project.name);
     if (!target) {
@@ -2860,7 +3458,9 @@ var Amender = class {
     this.planned.push({
       file: root,
       display: this.displayName(root),
-      added: [`${amendment.symbol}, its translations and its capability grants`],
+      added: [
+        `${amendment.symbol}, its translations and its capability grants`
+      ],
       content: result.source
     });
   }
@@ -2915,7 +3515,9 @@ var Amender = class {
     return void 0;
   }
   entryStylesheet(project) {
-    const styles = asObject3(asObject3(this.buildTarget(project.name)?.value)?.["options"])?.["styles"];
+    const styles = asObject3(
+      asObject3(this.buildTarget(project.name)?.value)?.["options"]
+    )?.["styles"];
     if (!Array.isArray(styles)) {
       return void 0;
     }
@@ -3077,7 +3679,7 @@ function replaceSymlinkEntry(absolute) {
 }
 
 // src/lib/run.ts
-var VERSION = "0.7.6";
+var VERSION = "0.7.7";
 function help() {
   const commands = SCAFFOLDS.map((s) => `  ${s.name.padEnd(16)}${s.summary}`);
   return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomweaver/cli",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "LoomWeaver scaffolding CLI: generates weavers, distributions and integrations into any project — no Nx workspace, no LoomWeaver checkout and no AI assistant required.",
   "keywords": [
     "loomweaver",