Desktop app that records your on-screen work session and uses the GitHub Copilot SDK to reconstruct it as an intent + ordered steps, then builds a reusable Skill or Automation for Microsoft Autopilots like Scout, Microsoft Copilot Cowork, or Copilot Studio.
TypeScript agent-skillsai-agentsautomationcopilotcopilot-clicopilot-coworkcopilot-studioelectronmicrosoft-scoutscreen-recording
refactor: centralize target architecture registry (#28)
Ramakrishnan Ramane95b69059c4d
diff --git a/common/architecture-registry.test.ts b/common/architecture-registry.test.tsnew file mode 100644index 0000000..ef18474--- /dev/null+++ b/common/architecture-registry.test.ts@@ -0,0 +1,85 @@+import assert from "node:assert/strict";+import test from "node:test";++import {+ ARCHITECTURES,+ SkillArchitecture,+ TARGETS,+ defineArchitectures,+ enabledArchitectureLabels,+} from "./architecture-registry";++test("the manifest derives architecture validation and target availability", () => {+ assert.deepEqual(SkillArchitecture.options, [+ "scout",+ "cowork",+ "copilot-studio",+ ]);+ assert.equal(SkillArchitecture.safeParse("generic").success, false);++ assert.deepEqual(+ ARCHITECTURES.map(({ id, enabled }) => [id, enabled]),+ [+ ["scout", true],+ ["cowork", true],+ ["copilot-studio", false],+ ],+ );+ assert.deepEqual(+ TARGETS.map(({ architecture, kind, enabled }) => [+ architecture,+ kind,+ enabled,+ ]),+ [+ ["scout", "skill", true],+ ["scout", "automation", true],+ ["cowork", "skill", true],+ ["copilot-studio", "skill", false],+ ],+ );++ assert.deepEqual(enabledArchitectureLabels("skill"), ["Scout", "Cowork"]);+ assert.deepEqual(enabledArchitectureLabels("automation"), ["Scout"]);+});++test("architecture definitions reject invalid registry shapes", () => {+ const skill = {+ kind: "skill" as const,+ label: "Skill",+ enabled: true,+ note: "Enabled.",+ };++ assert.throws(+ () => defineArchitectures([]),+ /Architecture manifest must contain at least one architecture/,+ );+ assert.throws(+ () =>+ defineArchitectures([+ { id: "duplicate", label: "First", note: "First.", targets: [skill] },+ { id: "duplicate", label: "Second", note: "Second.", targets: [skill] },+ ]),+ /Duplicate architecture id "duplicate"/,+ );+ assert.throws(+ () =>+ defineArchitectures([+ { id: "empty", label: "Empty", note: "Empty.", targets: [] },+ ]),+ /Architecture "empty" must declare at least one target/,+ );+ assert.throws(+ () =>+ defineArchitectures([+ {+ id: "duplicate-kind",+ label: "Duplicate kind",+ note: "Invalid.",+ targets: [skill, { ...skill, label: "Another skill" }],+ },+ ]),+ /Architecture "duplicate-kind" declares "skill" more than once/,+ );+});diff --git a/common/architecture-registry.ts b/common/architecture-registry.tsnew file mode 100644index 0000000..3490dac--- /dev/null+++ b/common/architecture-registry.ts@@ -0,0 +1,162 @@+import { z } from "zod";++export const BUILD_KINDS = ["skill", "automation"] as const;+export const BuildKind = z.enum(BUILD_KINDS);+export type BuildKind = z.infer<typeof BuildKind>;++export interface ArchitectureTargetDefinition {+ kind: BuildKind;+ label: string;+ enabled: boolean;+ note: string;+}++export interface ArchitectureDefinition<Id extends string = string> {+ id: Id;+ label: string;+ note: string;+ targets: readonly ArchitectureTargetDefinition[];+}++export function defineArchitectures<+ const T extends readonly ArchitectureDefinition[],+>(definitions: T): T {+ if (definitions.length === 0) {+ throw new Error("Architecture manifest must contain at least one architecture.");+ }++ const ids = new Set<string>();+ for (const definition of definitions) {+ if (ids.has(definition.id)) {+ throw new Error(`Duplicate architecture id "${definition.id}".`);+ }+ ids.add(definition.id);++ if (definition.targets.length === 0) {+ throw new Error(`Architecture "${definition.id}" must declare at least one target.`);+ }++ const kinds = new Set<BuildKind>();+ for (const target of definition.targets) {+ if (kinds.has(target.kind)) {+ throw new Error(+ `Architecture "${definition.id}" declares "${target.kind}" more than once.`,+ );+ }+ kinds.add(target.kind);+ }+ }++ return definitions;+}++export const ARCHITECTURE_MANIFEST = defineArchitectures([+ {+ id: "scout",+ label: "Scout",+ note: "Microsoft Scout: native WorkIQ, browser, files, and built-in skills.",+ targets: [+ {+ kind: "skill",+ label: "Scout skill",+ enabled: true,+ note: "An on-demand skill Scout runs when its description matches the task.",+ },+ {+ kind: "automation",+ label: "Scout automation",+ enabled: true,+ note: "A scheduled, multi-step automation Scout runs on a trigger.",+ },+ ],+ },+ {+ id: "cowork",+ label: "Cowork",+ note:+ "Microsoft 365 Copilot (Cowork): native Teams, Outlook, Calendar, " ++ "SharePoint, files, and built-in skills.",+ targets: [+ {+ kind: "skill",+ label: "Cowork skill",+ enabled: true,+ note: "An on-demand skill for Microsoft 365 Copilot (Cowork) you export and install.",+ },+ ],+ },+ {+ id: "copilot-studio",+ label: "Copilot Studio",+ note: "Coming soon.",+ targets: [+ {+ kind: "skill",+ label: "Copilot Studio",+ enabled: false,+ note: "Coming soon.",+ },+ ],+ },+] as const);++export type SkillArchitecture = (typeof ARCHITECTURE_MANIFEST)[number]["id"];++// The manifest validator guarantees a non-empty list; map preserves the ID union.+const architectureIds = ARCHITECTURE_MANIFEST.map(({ id }) => id) as [+ SkillArchitecture,+ ...SkillArchitecture[],+];++export const SkillArchitecture = z.enum(architectureIds);++export interface ArchitectureOption {+ id: SkillArchitecture;+ label: string;+ enabled: boolean;+ note: string;+}++export interface BuildTarget {+ kind: BuildKind;+ architecture: SkillArchitecture;+ label: string;+ enabled: boolean;+ note: string;+}++export const ARCHITECTURES: readonly ArchitectureOption[] = ARCHITECTURE_MANIFEST.map(+ ({ id, label, note, targets }) => ({+ id,+ label,+ enabled: targets.some((target) => target.enabled),+ note,+ }),+);++/**+ * Build targets shown up front, in order. Automation support is architecture-specific,+ * so the target kind and architecture are chosen together before planning begins.+ */+export const TARGETS: readonly BuildTarget[] = ARCHITECTURE_MANIFEST.flatMap(+ ({ id, targets }) =>+ targets.map((target) => ({+ kind: target.kind,+ architecture: id,+ label: target.label,+ enabled: target.enabled,+ note: target.note,+ })),+);++export function enabledArchitectureLabels(+ kind: BuildKind,+ definitions: readonly ArchitectureDefinition<SkillArchitecture>[] =+ ARCHITECTURE_MANIFEST,+): string[] {+ return definitions+ .filter((definition) =>+ definition.targets.some((target) => target.kind === kind && target.enabled),+ )+ .map((definition) => definition.label);+}diff --git a/common/skill.ts b/common/skill.tsindex 4697372..97f4926 100644--- a/common/skill.ts+++ b/common/skill.ts@@ -1,7 +1,10 @@import { z } from "zod";+import { SkillArchitecture } from "./architecture-registry";import { migrateLegacyInputsToValues, renderValues, ValueSchema } from "./values";+export * from "./architecture-registry";+/*** The Skill Builder's contract. From an *approved* {@link Analysis} the multi-turn* Copilot agent first proposes a **plan** ({@link SkillPlan}) — how it will@@ -13,84 +16,6 @@ import { migrateLegacyInputsToValues, renderValues, ValueSchema } from "./values* *input*); this is the builder's *output*.*/-/** Agent architectures a skill can target. Scout and Cowork are enabled today. */-export const SkillArchitecture = z.enum(["scout", "cowork", "copilot-studio"]);-export type SkillArchitecture = z.infer<typeof SkillArchitecture>;--/** UI metadata for the architecture selector (shared so main + renderer agree). */-export interface ArchitectureOption {- id: SkillArchitecture;- label: string;- /** Enabled targets can be built today; the rest are shown greyed out. */- enabled: boolean;- /** One-line reason / "coming soon" note shown under the option. */- note: string;-}--export const ARCHITECTURES: readonly ArchitectureOption[] = [- { id: "scout", label: "Scout", enabled: true, note: "Microsoft Scout: native WorkIQ, browser, files, and built-in skills." },- { id: "cowork", label: "Cowork", enabled: true, note: "Microsoft 365 Copilot (Cowork): native Teams, Outlook, Calendar, SharePoint, files, and built-in skills." },- { id: "copilot-studio", label: "Copilot Studio", enabled: false, note: "Coming soon." },-] as const;--/**- * The kind of artifact the builder produces from an approved analysis. A **skill**- * is an on-demand, description-triggered `SKILL.md`; an **automation** is a- * scheduled/condition-triggered, multi-step procedure. The two are built by- * separate final-stage agents because their plans have different shapes.- */-export const BuildKind = z.enum(["skill", "automation"]);-export type BuildKind = z.infer<typeof BuildKind>;--/** One selectable option in the "What do you want to build?" target picker. */-export interface BuildTarget {- kind: BuildKind;- architecture: SkillArchitecture;- /** Card label, e.g. "Scout automation". */- label: string;- /** Enabled targets can be built today; the rest are shown greyed out. */- enabled: boolean;- /** One-line note shown under the option. */- note: string;-}--/**- * The build targets shown up front, in order. Scout has both a skill and an automation- * target; Cowork has a skill target (export/download only). Automations are deeply- * platform-specific, so the target — not just the architecture — is chosen before the- * builder plans. copilot-studio is shown as a single greyed "coming soon" card.- */-export const TARGETS: readonly BuildTarget[] = [- {- kind: "skill",- architecture: "scout",- label: "Scout skill",- enabled: true,- note: "An on-demand skill Scout runs when its description matches the task.",- },- {- kind: "automation",- architecture: "scout",- label: "Scout automation",- enabled: true,- note: "A scheduled, multi-step automation Scout runs on a trigger.",- },- {- kind: "skill",- architecture: "cowork",- label: "Cowork skill",- enabled: true,- note: "An on-demand skill for Microsoft 365 Copilot (Cowork) you export and install.",- },- {- kind: "skill",- architecture: "copilot-studio",- label: "Copilot Studio",- enabled: false,- note: "Coming soon.",- },-] as const;-/*** A generalized step is either a **calculation** (reads, derives, decides, or formats* — no external side effect) or an **action** (changes the world: submit, send, create,diff --git a/electron/architectures/catalogue-provider.ts b/electron/architectures/catalogue-provider.tsnew file mode 100644index 0000000..b404315--- /dev/null+++ b/electron/architectures/catalogue-provider.ts@@ -0,0 +1,175 @@+import { z } from "zod";++import {+ ARCHITECTURE_MANIFEST,+ BUILD_KINDS,+ SkillArchitecture,+ defineArchitectures,+ enabledArchitectureLabels,+ type ArchitectureDefinition,+ type BuildKind,+} from "../../common/architecture-registry";++const NonEmptyCatalogueString = z.string().refine(+ (value) => value.trim().length > 0,+ "must not be empty",+);++export const CataloguePayloadSchema = z+ .object({+ version: NonEmptyCatalogueString,+ content: NonEmptyCatalogueString,+ })+ .strict();+export type CataloguePayload = z.infer<typeof CataloguePayloadSchema>;++export const ArchitectureCatalogueProviderSchema = z+ .object({+ architecture: SkillArchitecture,+ skill: CataloguePayloadSchema.optional(),+ automation: CataloguePayloadSchema.optional(),+ })+ .strict()+ .refine((provider) => provider.skill || provider.automation, {+ message: "must provide at least one catalogue payload",+ });+export type ArchitectureCatalogueProvider = z.infer<+ typeof ArchitectureCatalogueProviderSchema+>;++const CatalogueModuleSchema = z.object({+ default: ArchitectureCatalogueProviderSchema,+});++export function defineCatalogueProvider<+ const T extends ArchitectureCatalogueProvider,+>(provider: T): T {+ ArchitectureCatalogueProviderSchema.parse(provider);+ return provider;+}++function formatIssues(error: z.ZodError): string {+ return error.issues+ .map((issue) => `${issue.path.join(".") || "value"}: ${issue.message}`)+ .join("; ");+}++export function providersFromModules(+ modules: Readonly<Record<string, unknown>>,+): ArchitectureCatalogueProvider[] {+ return Object.entries(modules).map(([path, module]) => {+ const parsed = CatalogueModuleSchema.safeParse(module);+ if (!parsed.success) {+ throw new Error(+ `Invalid catalogue provider module "${path}": ${formatIssues(parsed.error)}`,+ );+ }+ return parsed.data.default;+ });+}++export interface CatalogueRegistry {+ catalogueFor(+ architecture: SkillArchitecture,+ kind: BuildKind,+ ): CataloguePayload | null;+ requireCatalogue(+ architecture: SkillArchitecture,+ kind: BuildKind,+ ): CataloguePayload;+}++function formatChoices(labels: readonly string[]): string {+ if (labels.length === 0) return "";+ if (labels.length === 1) return labels[0];+ if (labels.length === 2) return `${labels[0]} or ${labels[1]}`;+ return `${labels.slice(0, -1).join(", ")}, or ${labels[labels.length - 1]}`;+}++export function createCatalogueRegistry(+ providerInputs: readonly unknown[],+ manifest: readonly ArchitectureDefinition<SkillArchitecture>[] =+ ARCHITECTURE_MANIFEST,+): CatalogueRegistry {+ defineArchitectures(manifest);++ const definitions = new Map(+ manifest.map((definition) => [definition.id, definition]),+ );+ const providers = new Map<+ SkillArchitecture,+ ArchitectureCatalogueProvider+ >();++ for (const [index, input] of providerInputs.entries()) {+ const parsed = ArchitectureCatalogueProviderSchema.safeParse(input);+ if (!parsed.success) {+ throw new Error(+ `Invalid catalogue provider at index ${index}: ${formatIssues(parsed.error)}`,+ );+ }++ const provider = parsed.data;+ const definition = definitions.get(provider.architecture);+ if (!definition) {+ throw new Error(+ `Unknown architecture "${provider.architecture}" in catalogue provider.`,+ );+ }+ if (providers.has(provider.architecture)) {+ throw new Error(+ `Duplicate catalogue provider for architecture "${provider.architecture}".`,+ );+ }++ for (const kind of BUILD_KINDS) {+ if (+ provider[kind] &&+ !definition.targets.some((target) => target.kind === kind)+ ) {+ throw new Error(+ `Architecture "${provider.architecture}" does not declare target kind "${kind}".`,+ );+ }+ }++ providers.set(provider.architecture, provider);+ }++ for (const definition of manifest) {+ const provider = providers.get(definition.id);+ for (const target of definition.targets) {+ if (target.enabled && !provider?.[target.kind]) {+ throw new Error(+ `Enabled target "${target.label}" (${definition.id}:${target.kind}) ` ++ "is missing a catalogue payload.",+ );+ }+ }+ }++ const catalogueFor = (+ architecture: SkillArchitecture,+ kind: BuildKind,+ ): CataloguePayload | null => {+ const target = definitions+ .get(architecture)+ ?.targets.find((candidate) => candidate.kind === kind);+ if (!target?.enabled) return null;+ return providers.get(architecture)?.[kind] ?? null;+ };++ const requireCatalogue = (+ architecture: SkillArchitecture,+ kind: BuildKind,+ ): CataloguePayload => {+ const catalogue = catalogueFor(architecture, kind);+ if (catalogue) return catalogue;++ const labels = enabledArchitectureLabels(kind, manifest);+ const choices = labels.length ? ` Choose ${formatChoices(labels)}.` : "";+ throw new Error(`That target architecture isn't available yet.${choices}`);+ };++ return { catalogueFor, requireCatalogue };+}diff --git a/electron/architectures/catalogue-registry.test.ts b/electron/architectures/catalogue-registry.test.tsnew file mode 100644index 0000000..ff96871--- /dev/null+++ b/electron/architectures/catalogue-registry.test.ts@@ -0,0 +1,192 @@+import assert from "node:assert/strict";+import { createHash } from "node:crypto";+import test from "node:test";++import {+ ARCHITECTURE_MANIFEST,+ defineArchitectures,+} from "../../common/architecture-registry";+import {+ createCatalogueRegistry,+ defineCatalogueProvider,+ providersFromModules,+} from "./catalogue-provider";+import coworkCatalogueProvider from "./catalogues/cowork-catalogue";+import scoutCatalogueProvider from "./catalogues/scout-catalogue";++const scoutProvider = defineCatalogueProvider({+ architecture: "scout",+ skill: { version: "scout-skill-v1", content: "Scout skill catalogue" },+ automation: {+ version: "scout-automation-v1",+ content: "Scout automation catalogue",+ },+});++const coworkProvider = defineCatalogueProvider({+ architecture: "cowork",+ skill: { version: "cowork-skill-v1", content: "Cowork skill catalogue" },+});++function sha256(content: string): string {+ return createHash("sha256").update(content, "utf8").digest("hex");+}++function providersWithScoutSkill(skill: unknown): readonly unknown[] {+ return [+ {+ architecture: "scout",+ skill,+ automation: scoutProvider.automation,+ },+ coworkProvider,+ ];+}++test("the registry resolves enabled catalogues and derives unavailable errors", () => {+ const registry = createCatalogueRegistry([scoutProvider, coworkProvider]);++ assert.deepEqual(registry.catalogueFor("scout", "skill"), scoutProvider.skill);+ assert.deepEqual(+ registry.catalogueFor("scout", "automation"),+ scoutProvider.automation,+ );+ assert.deepEqual(registry.catalogueFor("cowork", "skill"), coworkProvider.skill);+ assert.equal(registry.catalogueFor("cowork", "automation"), null);+ assert.throws(+ () => registry.requireCatalogue("cowork", "automation"),+ /That target architecture isn't available yet\. Choose Scout\./,+ );+});++test("disabled targets stay unavailable even when catalogue content is staged", () => {+ const stagedCopilotStudioProvider = defineCatalogueProvider({+ architecture: "copilot-studio",+ skill: {+ version: "copilot-studio-v1",+ content: "Copilot Studio skill catalogue",+ },+ });+ const registry = createCatalogueRegistry([+ scoutProvider,+ coworkProvider,+ stagedCopilotStudioProvider,+ ]);++ assert.equal(registry.catalogueFor("copilot-studio", "skill"), null);+ assert.throws(+ () => registry.requireCatalogue("copilot-studio", "skill"),+ /That target architecture isn't available yet\. Choose Scout or Cowork\./,+ );+});++test("the registry rejects missing, duplicate, unknown, and undeclared providers", () => {+ assert.throws(+ () => createCatalogueRegistry([scoutProvider]),+ /Enabled target "Cowork skill" \(cowork:skill\) is missing a catalogue payload/,+ );+ assert.throws(+ () => createCatalogueRegistry([scoutProvider, scoutProvider, coworkProvider]),+ /Duplicate catalogue provider for architecture "scout"/,+ );++ const scoutOnlyManifest = defineArchitectures([ARCHITECTURE_MANIFEST[0]]);+ assert.throws(+ () => createCatalogueRegistry([coworkProvider], scoutOnlyManifest),+ /Unknown architecture "cowork" in catalogue provider/,+ );++ assert.throws(+ () =>+ createCatalogueRegistry([+ scoutProvider,+ {+ ...coworkProvider,+ automation: {+ version: "cowork-automation-v1",+ content: "Cowork automation catalogue",+ },+ },+ ]),+ /Architecture "cowork" does not declare target kind "automation"/,+ );+});++test("provider payloads and discovered module shapes are validated strictly", () => {+ for (const [skill, error] of [+ [+ { version: "", content: "Scout skill catalogue" },+ /skill\.version: must not be empty/,+ ],+ [+ { version: "scout-skill-v1", content: " " },+ /skill\.content: must not be empty/,+ ],+ ] as const) {+ assert.throws(+ () => createCatalogueRegistry(providersWithScoutSkill(skill)),+ error,+ );+ }++ assert.throws(+ () => createCatalogueRegistry([{ architecture: "copilot-studio" }]),+ /must provide at least one catalogue payload/,+ );+ assert.throws(+ () =>+ createCatalogueRegistry([+ scoutProvider,+ {+ architecture: "cowork",+ skills: coworkProvider.skill,+ },+ ]),+ /Unrecognized key: "skills"/,+ );+ assert.throws(+ () => providersFromModules({ "./missing-default.catalogue.ts": {} }),+ /Invalid catalogue provider module ".\/missing-default\.catalogue\.ts"/,+ );+ assert.throws(+ () =>+ providersFromModules({+ "./unknown.catalogue.ts": {+ default: {+ architecture: "generic",+ skill: { version: "generic-v1", content: "Generic catalogue" },+ },+ },+ }),+ /Invalid catalogue provider module ".\/unknown\.catalogue\.ts"/,+ );+});++test("real providers preserve versions, content, and the support matrix", () => {+ const registry = createCatalogueRegistry([+ scoutCatalogueProvider,+ coworkCatalogueProvider,+ ]);++ // These hashes prove catalogue moves are byte-for-byte. Intentional catalogue+ // changes must bump the corresponding version and update its hash here.+ const scoutSkill = registry.requireCatalogue("scout", "skill");+ assert.equal(scoutSkill.version, "2026-07-26");+ assert.equal(+ sha256(scoutSkill.content),+ "2621869fe246edf1244a528824853ab5bc455811442d26c24485e48e1c2e30a7",+ );+ const scoutAutomation = registry.requireCatalogue("scout", "automation");+ assert.equal(scoutAutomation.version, "2026-07-26");+ assert.equal(+ sha256(scoutAutomation.content),+ "0fbad5a4324b270bcec5a1c8eb21c4584991093beb5802e9af99caefeb4bd475",+ );++ const coworkSkill = registry.requireCatalogue("cowork", "skill");+ assert.equal(coworkSkill.version, "2026-07-28");+ assert.equal(+ sha256(coworkSkill.content),+ "39ffbdf3225ce47eecd735252558cffe860eb6a207782a2f604a8a57fb9a0f68",+ );+});diff --git a/electron/architectures/catalogue-registry.ts b/electron/architectures/catalogue-registry.tsnew file mode 100644index 0000000..bbc0bea--- /dev/null+++ b/electron/architectures/catalogue-registry.ts@@ -0,0 +1,17 @@+/// <reference types="vite/client" />++import {+ createCatalogueRegistry,+ providersFromModules,+} from "./catalogue-provider";++const providerModules = import.meta.glob("./catalogues/*-catalogue.ts", {+ eager: true,+});++const registry = createCatalogueRegistry(+ providersFromModules(providerModules),+);++export const catalogueFor = registry.catalogueFor;+export const requireCatalogue = registry.requireCatalogue;diff --git a/electron/skillbuilder/cowork-catalog.ts b/electron/architectures/catalogues/cowork-catalogue.tssimilarity index 97%rename from electron/skillbuilder/cowork-catalog.tsrename to electron/architectures/catalogues/cowork-catalogue.tsindex 888f7a5..607b1a7 100644--- a/electron/skillbuilder/cowork-catalog.ts+++ b/electron/architectures/catalogues/cowork-catalogue.ts@@ -1,3 +1,5 @@+import { defineCatalogueProvider } from "../catalogue-provider";+/*** A **static, versioned** snapshot of the Cowork (Microsoft 365 Copilot) agent's native* capabilities, embedded into the builder's system prompt. End users won't have the Cowork@@ -132,7 +134,10 @@ ${COWORK_NATIVE_CAPABILITIES}- Keep it concise and imperative. Include a short "When to use" and the ordered steps.`.trim();-/** The Cowork catalogue, or null. Exposed so {@link catalogueFor} can dispatch on it. */-export function coworkCatalogue(): string {- return COWORK_CATALOGUE;-}+export default defineCatalogueProvider({+ architecture: "cowork",+ skill: {+ version: COWORK_CATALOGUE_VERSION,+ content: COWORK_CATALOGUE,+ },+});diff --git a/electron/skillbuilder/scout-catalog.ts b/electron/architectures/catalogues/scout-catalogue.tssimilarity index 67%rename from electron/skillbuilder/scout-catalog.tsrename to electron/architectures/catalogues/scout-catalogue.tsindex c0da929..ab7fd62 100644--- a/electron/skillbuilder/scout-catalog.ts+++ b/electron/architectures/catalogues/scout-catalogue.ts@@ -1,5 +1,4 @@-import type { SkillArchitecture } from "../../common/skill";-import { coworkCatalogue } from "./cowork-catalog";+import { defineCatalogueProvider } from "../catalogue-provider";/*** A **static, versioned** snapshot of the target agent's native capabilities,@@ -116,14 +115,70 @@ ${SCOUT_NATIVE_CAPABILITIES}- Keep it concise and imperative. Include a short "When to use" and the ordered steps.`.trim();-/** The catalogue for a target architecture, or null if none is available yet. */-export function catalogueFor(architecture: SkillArchitecture): string | null {- switch (architecture) {- case "scout":- return SCOUT_CATALOGUE;- case "cowork":- return coworkCatalogue();- default:- return null;- }-}+/**+ * The Automation Builder's Scout catalogue. Reuses the shared native-capability+ * snapshot ({@link SCOUT_NATIVE_CAPABILITIES}) but frames it for **automations** —+ * a scheduled/condition trigger plus ordered steps, where each step is a+ * natural-language **prompt** to the Scout agent (not a `SKILL.md` procedure).+ * Authored by inspecting `~/projects/m` (electron/automations/*). Refresh when+ * Scout's automation model or native tools change.+ */+export const SCOUT_AUTOMATION_CATALOGUE_VERSION = "2026-07-26";++const SCOUT_AUTOMATION_CATALOGUE = `+# Target: Microsoft Scout — automation catalogue (built-ins only)++A Scout **automation** is a **trigger** plus an ordered list of **steps**. Scout runs+the steps in order on the trigger; each step is a natural-language **prompt** the Scout+agent executes with its native tools (below). Automations are imported into Scout from a+bundle folder — they are NOT auto-loaded like skills.++## Trigger++- **schedule** (default) — the automation runs on a clock. Express it as natural language+ such as: "every weekday at 9am", "daily at 8:30am", "every day at 9am, 2pm, and 6pm",+ "every 30 minutes", or "every hour at :15". The three shapes are:+ - **single** — one time of day (optionally only on some weekdays).+ - **interval** — every N minutes (N must divide 1440 evenly), from an anchor time.+ - **multi** — several fixed times of day.+- **condition** — the automation checks a natural-language condition on a cadence and only+ runs when it's true (e.g. "when a new CSV appears in ~/Downloads"). Use this only when the+ recording clearly implies an event trigger; otherwise prefer a schedule.++A recording captures ONE run of the task and usually has NO "when to run" signal — so you+must PROPOSE a sensible default schedule (state your assumption) and let the user correct it+in plain language.++## Steps — each is a prompt++- Break the generalized task into a few ordered steps. Each step has a short **label** and a+ **prompt** — an imperative instruction to the Scout agent for that part of the task.+- Write prompts that GENERALIZE: if the recording acted on N specific items, the prompt tells+ the agent to handle every item of that kind, not the specific examples recorded.+- Prompts should prefer Scout's native tools (below) over UI replay, and say briefly why.+- Self-resolving prompts: reference a genuinely fixed literal by its \`{{id}}\` value token,+ and for anything that varies tell the agent to locate it on the device or read it from M365.+ An unattended automation can't stop to ask a human, so never depend on a user-provided value.+- Keep destructive or send/create actions explicit so the user sees them in the plan.++${SCOUT_NATIVE_CAPABILITIES}++## Writing the automation++- Propose a trigger (a schedule by default) and 2–6 generalized, native-tool-first steps.+- Prefer the native tools above; use the device's CLI (e.g. \`gh\` for GitHub) over the+ browser, and only use the browser for genuine UI-only steps (no API and no CLI).+- Give the automation a clear \`description\` of what it does and when it runs.+`.trim();++export default defineCatalogueProvider({+ architecture: "scout",+ skill: {+ version: SCOUT_CATALOGUE_VERSION,+ content: SCOUT_CATALOGUE,+ },+ automation: {+ version: SCOUT_AUTOMATION_CATALOGUE_VERSION,+ content: SCOUT_AUTOMATION_CATALOGUE,+ },+});diff --git a/electron/automationbuilder/builder.ts b/electron/automationbuilder/builder.tsindex 66a3d4d..83de506 100644--- a/electron/automationbuilder/builder.ts+++ b/electron/automationbuilder/builder.ts@@ -16,13 +16,13 @@ import {} from "../../common/automation";import type { AutomationBuildInput, AutomationBuildProgress } from "../../common/ipc";import { slugifySkillName, type SkillArchitecture } from "../../common/skill";+import { requireCatalogue } from "../architectures/catalogue-registry";import { AgentBuilder, type BaseLive } from "../builders/agent-builder";import { createReadTools } from "../builders/read-tools";import { loadPersistedAnalysis } from "../describer/describer";import { createLogger } from "../logger";import { isValidSessionId, sessionDir } from "../recorder/session-store";import { AUTOMATION_BUILDER_INSTRUCTIONS } from "./instructions";-import { automationCatalogueFor } from "./scout-automation-catalog";import { createAutomationBuilderTools } from "./tools";const log = createLogger("AutomationBuilder");@@ -86,9 +86,7 @@ export class AutomationBuilder extends AgentBuilder<LiveBuild> {async build(input: AutomationBuildInput): Promise<AutomationPlan> {const { sessionId, architecture, feedback } = input;if (this.active.has(sessionId)) throw new Error("A build is already running for this session.");- if (!automationCatalogueFor(architecture)) {- throw new Error("That target architecture isn't available yet. Choose Scout.");- }+ requireCatalogue(architecture, "automation");const analysis = loadPersistedAnalysis(sessionId);if (!analysis) throw new Error("There is no analysis for this recording yet.");@@ -171,7 +169,7 @@ export class AutomationBuilder extends AgentBuilder<LiveBuild> {}),];- const catalogue = automationCatalogueFor(architecture) ?? "";+ const catalogue = requireCatalogue(architecture, "automation").content;const systemContent = `${AUTOMATION_BUILDER_INSTRUCTIONS}\n\n${catalogue}`.trim();const client = await this.ensureClient();diff --git a/electron/automationbuilder/scout-automation-catalog.ts b/electron/automationbuilder/scout-automation-catalog.tsdeleted file mode 100644index c2a8c4c..0000000--- a/electron/automationbuilder/scout-automation-catalog.ts+++ /dev/null@@ -1,63 +0,0 @@-import type { SkillArchitecture } from "../../common/skill";-import { SCOUT_NATIVE_CAPABILITIES } from "../skillbuilder/scout-catalog";--/**- * The Automation Builder's Scout catalogue. Reuses the shared native-capability- * snapshot ({@link SCOUT_NATIVE_CAPABILITIES}) but frames it for **automations** —- * a scheduled/condition trigger plus ordered steps, where each step is a- * natural-language **prompt** to the Scout agent (not a `SKILL.md` procedure).- * Authored by inspecting `~/projects/m` (electron/automations/*). Refresh when- * Scout's automation model or native tools change.- */-export const SCOUT_AUTOMATION_CATALOGUE_VERSION = "2026-07-26";--const SCOUT_AUTOMATION_CATALOGUE = `-# Target: Microsoft Scout — automation catalogue (built-ins only)--A Scout **automation** is a **trigger** plus an ordered list of **steps**. Scout runs-the steps in order on the trigger; each step is a natural-language **prompt** the Scout-agent executes with its native tools (below). Automations are imported into Scout from a-bundle folder — they are NOT auto-loaded like skills.--## Trigger--- **schedule** (default) — the automation runs on a clock. Express it as natural language- such as: "every weekday at 9am", "daily at 8:30am", "every day at 9am, 2pm, and 6pm",- "every 30 minutes", or "every hour at :15". The three shapes are:- - **single** — one time of day (optionally only on some weekdays).- - **interval** — every N minutes (N must divide 1440 evenly), from an anchor time.- - **multi** — several fixed times of day.-- **condition** — the automation checks a natural-language condition on a cadence and only- runs when it's true (e.g. "when a new CSV appears in ~/Downloads"). Use this only when the- recording clearly implies an event trigger; otherwise prefer a schedule.--A recording captures ONE run of the task and usually has NO "when to run" signal — so you-must PROPOSE a sensible default schedule (state your assumption) and let the user correct it-in plain language.--## Steps — each is a prompt--- Break the generalized task into a few ordered steps. Each step has a short **label** and a- **prompt** — an imperative instruction to the Scout agent for that part of the task.-- Write prompts that GENERALIZE: if the recording acted on N specific items, the prompt tells- the agent to handle every item of that kind, not the specific examples recorded.-- Prompts should prefer Scout's native tools (below) over UI replay, and say briefly why.-- Self-resolving prompts: reference a genuinely fixed literal by its \`{{id}}\` value token,- and for anything that varies tell the agent to locate it on the device or read it from M365.- An unattended automation can't stop to ask a human, so never depend on a user-provided value.-- Keep destructive or send/create actions explicit so the user sees them in the plan.--${SCOUT_NATIVE_CAPABILITIES}--## Writing the automation--- Propose a trigger (a schedule by default) and 2–6 generalized, native-tool-first steps.-- Prefer the native tools above; use the device's CLI (e.g. \`gh\` for GitHub) over the- browser, and only use the browser for genuine UI-only steps (no API and no CLI).-- Give the automation a clear \`description\` of what it does and when it runs.-`.trim();--/** The automation catalogue for a target architecture, or null if unavailable. */-export function automationCatalogueFor(architecture: SkillArchitecture): string | null {- return architecture === "scout" ? SCOUT_AUTOMATION_CATALOGUE : null;-}diff --git a/electron/skillbuilder/builder.ts b/electron/skillbuilder/builder.tsindex 6041f0f..6495a40 100644--- a/electron/skillbuilder/builder.ts+++ b/electron/skillbuilder/builder.ts@@ -17,13 +17,13 @@ import {} from "../../common/skill";import { unresolvedTokens } from "../../common/values";import type { SkillBuildInput, SkillBuildProgress } from "../../common/ipc";+import { requireCatalogue } from "../architectures/catalogue-registry";import { AgentBuilder, type BaseLive } from "../builders/agent-builder";import { createReadTools } from "../builders/read-tools";import { loadPersistedAnalysis } from "../describer/describer";import { createLogger } from "../logger";import { isValidSessionId, sessionDir } from "../recorder/session-store";import { SKILL_BUILDER_INSTRUCTIONS } from "./instructions";-import { catalogueFor } from "./scout-catalog";import { createSkillBuilderTools } from "./tools";const log = createLogger("SkillBuilder");@@ -108,9 +108,7 @@ export class SkillBuilder extends AgentBuilder<LiveBuild> {async build(input: SkillBuildInput): Promise<SkillPlan> {const { sessionId, architecture, feedback } = input;if (this.active.has(sessionId)) throw new Error("A build is already running for this session.");- if (!catalogueFor(architecture)) {- throw new Error("That target architecture isn't available yet. Choose Scout or Cowork.");- }+ requireCatalogue(architecture, "skill");const analysis = loadPersistedAnalysis(sessionId);if (!analysis) throw new Error("There is no analysis for this recording yet.");@@ -227,7 +225,7 @@ export class SkillBuilder extends AgentBuilder<LiveBuild> {}),];- const catalogue = catalogueFor(architecture) ?? "";+ const catalogue = requireCatalogue(architecture, "skill").content;const systemContent = `${SKILL_BUILDER_INSTRUCTIONS}\n\n${catalogue}`.trim();const client = await this.ensureClient();diff --git a/evals/README.md b/evals/README.mdindex 8474fc4..57837ef 100644--- a/evals/README.md+++ b/evals/README.md@@ -177,7 +177,7 @@ one of two flavours:(`view`/pdf), and reading the mailbox via `workiq_*` rather than the Mail UI.This is the suite that drove the catalogue fix in-`electron/skillbuilder/scout-catalog.ts` (prefer first-class device CLIs — above+`electron/architectures/catalogues/scout-catalogue.ts` (prefer first-class device CLIs — aboveall `gh` — over the browser, platform-aware for zsh/bash vs PowerShell). When youadd a describer scenario, add the matching builder scenario so the pair stays inlockstep.diff --git a/evals/builder-imports.test.ts b/evals/builder-imports.test.tsnew file mode 100644index 0000000..adeea5d--- /dev/null+++ b/evals/builder-imports.test.ts@@ -0,0 +1,12 @@+import assert from "node:assert/strict";+import test from "node:test";++test("the eval loader imports both real builders without Vite", async () => {+ const [{ AutomationBuilder }, { SkillBuilder }] = await Promise.all([+ import("../electron/automationbuilder/builder"),+ import("../electron/skillbuilder/builder"),+ ]);++ assert.equal(typeof AutomationBuilder, "function");+ assert.equal(typeof SkillBuilder, "function");+});diff --git a/evals/hooks.mjs b/evals/hooks.mjsindex 35fa142..077871d 100644--- a/evals/hooks.mjs+++ b/evals/hooks.mjs@@ -1,7 +1,8 @@// A Node module-resolution hook that lets the eval harness run the app's// TypeScript source directly (no bundler), by:// 1. redirecting the lone `electron` dependency to a headless stub, and-// 2. resolving extensionless relative/absolute imports to their `.ts` file+// 2. redirecting Vite-only catalogue discovery to a Node filesystem adapter, and+// 3. resolving extensionless relative/absolute imports to their `.ts` file// (the project is authored Vite-style, without extensions).// Node itself strips/transforms the TypeScript (run with// `--experimental-transform-types`). Registered via register.mjs.@@ -11,6 +12,16 @@ import { fileURLToPath, pathToFileURL } from "node:url";const here = path.dirname(fileURLToPath(import.meta.url));const ELECTRON_STUB = pathToFileURL(path.join(here, "electron-stub.mjs")).href;+const CATALOGUE_REGISTRY = path.resolve(+ here,+ "..",+ "electron",+ "architectures",+ "catalogue-registry.ts",+);+const EVAL_CATALOGUE_REGISTRY = pathToFileURL(+ path.join(here, "lib", "catalogue-registry.ts"),+).href;export async function resolve(specifier, context, next) {if (specifier === "electron") {@@ -22,7 +33,13 @@ export async function resolve(specifier, context, next) {const base = path.resolve(path.dirname(fileURLToPath(context.parentURL)), specifier);for (const candidate of [`${base}.ts`, path.join(base, "index.ts")]) {if (existsSync(candidate)) {- return { url: pathToFileURL(candidate).href, shortCircuit: true };+ return {+ url:+ candidate === CATALOGUE_REGISTRY+ ? EVAL_CATALOGUE_REGISTRY+ : pathToFileURL(candidate).href,+ shortCircuit: true,+ };}}}diff --git a/evals/lib/catalogue-registry.ts b/evals/lib/catalogue-registry.tsnew file mode 100644index 0000000..542f67c--- /dev/null+++ b/evals/lib/catalogue-registry.ts@@ -0,0 +1,32 @@+import { readdir } from "node:fs/promises";++import {+ createCatalogueRegistry,+ providersFromModules,+} from "../../electron/architectures/catalogue-provider";++const cataloguesDirectory = new URL(+ "../../electron/architectures/catalogues/",+ import.meta.url,+);+const catalogueFiles = (+ await readdir(cataloguesDirectory, { withFileTypes: true })+)+ .filter((entry) => entry.isFile() && entry.name.endsWith("-catalogue.ts"))+ .sort((left, right) => left.name.localeCompare(right.name));++const providerModules = Object.fromEntries(+ await Promise.all(+ catalogueFiles.map(+ async (entry) =>+ [+ `./catalogues/${entry.name}`,+ await import(new URL(entry.name, cataloguesDirectory).href),+ ] as const,+ ),+ ),+);+const registry = createCatalogueRegistry(providersFromModules(providerModules));++export const catalogueFor = registry.catalogueFor;+export const requireCatalogue = registry.requireCatalogue;diff --git a/package.json b/package.jsonindex fa4c23c..868e017 100644--- a/package.json+++ b/package.json@@ -10,22 +10,22 @@"main": "dist-electron/main.js","scripts": {"dev": "vite",- "build:vite": "vite build",- "build": "tsc --noEmit && vite build",+ "build:vite": "vite build && node scripts/assert-catalogue-bundle-boundary.mjs",+ "build": "tsc --noEmit && npm run build:vite","typecheck": "tsc --noEmit","typecheck:evals": "tsc --noEmit -p evals/tsconfig.json",- "test": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs --test common/audio.test.ts common/microphone.test.ts common/narration.test.ts electron/recording-controls-bounds.test.ts electron/recording-privacy.test.ts electron/crash-guards.test.ts electron/recorder/controller.test.ts electron/recorder/session-store.test.ts electron/frames/extractor.test.ts electron/narration/audio-analysis.test.ts electron/narration/analyze-gate.test.ts electron/narration/transcribe.test.ts electron/narration/whisper.test.ts electron/sessions.test.ts electron/debug-bundle.test.ts scripts/compliance.test.mjs",+ "test": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs --test evals/builder-imports.test.ts common/architecture-registry.test.ts electron/architectures/catalogue-registry.test.ts common/audio.test.ts common/microphone.test.ts common/narration.test.ts electron/recording-controls-bounds.test.ts electron/recording-privacy.test.ts electron/crash-guards.test.ts electron/recorder/controller.test.ts electron/recorder/session-store.test.ts electron/frames/extractor.test.ts electron/narration/audio-analysis.test.ts electron/narration/analyze-gate.test.ts electron/narration/transcribe.test.ts electron/narration/whisper.test.ts electron/sessions.test.ts electron/debug-bundle.test.ts scripts/compliance.test.mjs","eval": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/run.ts","eval:builder": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/builder/run.ts","eval:skill": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/skillbuilder/run.ts","compliance:licenses": "node scripts/prepare-compliance.mjs --licenses-only","compliance:prepare": "node scripts/prepare-compliance.mjs","compliance:test": "node --test scripts/compliance.test.mjs",- "dist": "npm run compliance:prepare && node scripts/assert-generic-dist-platform.mjs && vite build && electron-builder --publish never",- "dist:win:x64": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs x64 && vite build && electron-builder --config.npmRebuild=false --publish never --win nsis --x64",- "dist:win:arm64": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs arm64 && vite build && electron-builder --config.npmRebuild=false --publish never --win nsis --arm64",- "dist:portable:mac": "npm run compliance:prepare && vite build && electron-builder --publish never --mac zip",- "dist:portable:win": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs x64 && vite build && electron-builder --config.npmRebuild=false --publish never --win portable --x64",+ "dist": "npm run compliance:prepare && node scripts/assert-generic-dist-platform.mjs && npm run build:vite && electron-builder --publish never",+ "dist:win:x64": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs x64 && npm run build:vite && electron-builder --config.npmRebuild=false --publish never --win nsis --x64",+ "dist:win:arm64": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs arm64 && npm run build:vite && electron-builder --config.npmRebuild=false --publish never --win nsis --arm64",+ "dist:portable:mac": "npm run compliance:prepare && npm run build:vite && electron-builder --publish never --mac zip",+ "dist:portable:win": "npm run compliance:prepare && node scripts/assert-native-windows-arch.mjs x64 && npm run build:vite && electron-builder --config.npmRebuild=false --publish never --win portable --x64","start": "electron ."},"dependencies": {diff --git a/scripts/assert-catalogue-bundle-boundary.mjs b/scripts/assert-catalogue-bundle-boundary.mjsnew file mode 100644index 0000000..ffde34b--- /dev/null+++ b/scripts/assert-catalogue-bundle-boundary.mjs@@ -0,0 +1,67 @@+import { readdir, readFile } from "node:fs/promises";+import path from "node:path";+import { fileURLToPath } from "node:url";++const CATALOGUE_HEADING = /^# Target:[^\r\n]+/gm;+const TEXT_EXTENSIONS = new Set([".html", ".js", ".mjs"]);+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");+const cataloguesDirectory = path.join(+ rootDir,+ "electron",+ "architectures",+ "catalogues",+);++async function catalogueMarkers() {+ const entries = (await readdir(cataloguesDirectory, { withFileTypes: true }))+ .filter((entry) => entry.isFile() && entry.name.endsWith("-catalogue.ts"))+ .sort((left, right) => left.name.localeCompare(right.name));+ const markers = [];++ for (const entry of entries) {+ const source = await readFile(+ path.join(cataloguesDirectory, entry.name),+ "utf8",+ );+ const headings = source.match(CATALOGUE_HEADING) ?? [];+ if (headings.length === 0) {+ throw new Error(+ `${entry.name} must contain at least one "# Target:" catalogue heading.`,+ );+ }+ markers.push(...headings.map((heading) => [entry.name, heading]));+ }++ if (markers.length === 0) {+ throw new Error("No architecture catalogue markers were found.");+ }+ return markers;+}++async function containsMarker(directory, marker) {+ for (const entry of await readdir(directory, { withFileTypes: true })) {+ const entryPath = path.join(directory, entry.name);+ if (entry.isDirectory()) {+ if (await containsMarker(entryPath, marker)) return true;+ continue;+ }+ if (+ TEXT_EXTENSIONS.has(path.extname(entry.name)) &&+ (await readFile(entryPath, "utf8")).includes(marker)+ ) {+ return true;+ }+ }+ return false;+}++for (const [name, marker] of await catalogueMarkers()) {+ if (await containsMarker(path.join(rootDir, "dist"), marker)) {+ throw new Error(`${name} catalogue content leaked into the renderer bundle.`);+ }+ if (!(await containsMarker(path.join(rootDir, "dist-electron"), marker))) {+ throw new Error(`${name} catalogue content is missing from the Electron bundle.`);+ }+}++console.log("Catalogue bundle boundary verified.");