Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
Templates create managed agents through agent management (CHOO-3481) (#851)
Louis Amaudruzcbd859215046
diff --git a/connectors/antigravity-cli/skills/switch/SKILL.md b/connectors/antigravity-cli/skills/switch/SKILL.mdindex ff15bf541..2c1343f2d 100644--- a/connectors/antigravity-cli/skills/switch/SKILL.md+++ b/connectors/antigravity-cli/skills/switch/SKILL.md@@ -813,7 +813,7 @@ failure-mode tools are covered in the sections just above.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/connectors/claude-code-plugin/skills/switch/SKILL.md b/connectors/claude-code-plugin/skills/switch/SKILL.mdindex 7b8ee7a2c..2c4a7097b 100644--- a/connectors/claude-code-plugin/skills/switch/SKILL.md+++ b/connectors/claude-code-plugin/skills/switch/SKILL.md@@ -836,7 +836,7 @@ failure-mode tools are covered in the sections just above.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/connectors/codex-plugin/skills/switch/SKILL.md b/connectors/codex-plugin/skills/switch/SKILL.mdindex af6157f85..472a1803b 100644--- a/connectors/codex-plugin/skills/switch/SKILL.md+++ b/connectors/codex-plugin/skills/switch/SKILL.md@@ -834,7 +834,7 @@ failure-mode tools are covered in the sections just above.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/connectors/cursor-cli/skills/switch/SKILL.md b/connectors/cursor-cli/skills/switch/SKILL.mdindex d5872f898..5eaa00ce3 100644--- a/connectors/cursor-cli/skills/switch/SKILL.md+++ b/connectors/cursor-cli/skills/switch/SKILL.md@@ -803,7 +803,7 @@ failure-mode tools are covered in the sections just above.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/connectors/opencode-plugin/skills/switch/SKILL.md b/connectors/opencode-plugin/skills/switch/SKILL.mdindex d3cb10b6a..863a6a6e2 100644--- a/connectors/opencode-plugin/skills/switch/SKILL.md+++ b/connectors/opencode-plugin/skills/switch/SKILL.md@@ -837,7 +837,7 @@ failure-mode tools are covered in the sections just above.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/console/apps/switch-console-desktop/src/main/core/agent-templates/controller.ts b/console/apps/switch-console-desktop/src/main/core/agent-templates/controller.tsindex 15dea5a47..d303daec8 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-templates/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-templates/controller.ts@@ -25,8 +25,12 @@ import {parseTemplateAgents,substituteAgentSlots,type TemplateAgents,+ isVersion2,+ parseYaml,templateKind,type TemplateKind,+ type Version2Rooms,+ version2Rooms,} from './template-document';import { summarizeTemplate, type TemplateSummary } from './template-summary';@@ -126,6 +130,10 @@ export const agentTemplatesController = createRPCController({/** Classify a document as an agent, room or group template. */kind: (params: { yamlText: string }): TemplateKind => templateKind(params.yamlText),+ /** A version 2 document's rooms and group; null for a version 1 document. */+ version2Rooms: (params: { yamlText: string }): Version2Rooms | null =>+ isVersion2(parseYaml(params.yamlText)) ? version2Rooms(params.yamlText) : null,+/** The agents a document creates. Empty for a room template. */parseAgents: (params: { yamlText: string; instructions?: string | null }): TemplateAgents =>parseTemplateAgents(params.yamlText, params.instructions ?? null),diff --git a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.test.ts b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.test.tsindex 5c515e0bd..cabceee8d 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.test.ts@@ -8,6 +8,7 @@ import {parseTemplateAgents,substituteAgentSlots,templateKind,+ version2Rooms,} from './template-document';const TRIAGE_PAIR = `@@ -239,3 +240,196 @@ describe('formOptions', () => {});});});++describe('parseTemplateAgents: what a template leaves unsaid', () => {+ it('reports each runtime setting an agent has no field or shared param for', () => {+ const { unsaid } = parseTemplateAgents(`+agent:+ name: helper+ provider: claude+ instructions: Help.+`);+ expect(unsaid).toEqual([+ { index: 0, label: 'helper', field: 'location' },+ { index: 0, label: 'helper', field: 'directory' },+ ]);+ });++ it('counts a param of that type no field reads as said for every agent', () => {+ const { unsaid } = parseTemplateAgents(`+params:+ provider: { type: provider, default: [claude] }+ where: { type: location, default: local }+ dir: { type: directory, default: "{$agents_dir}/{agent}" }+agents:+ - name: a+ instructions: A.+ - name: b+ instructions: B.+`);+ expect(unsaid).toEqual([]);+ });++ it('does not count a param one agent reads as said for another', () => {+ const { unsaid } = parseTemplateAgents(`+params:+ where: { type: location, default: local }+agents:+ - name: a+ provider: claude+ location: "{where}"+ directory: /tmp/a+ instructions: A.+ - name: b+ provider: claude+ directory: /tmp/b+ instructions: B.+`);+ expect(unsaid).toEqual([{ index: 1, label: 'b', field: 'location' }]);+ });++ it('records every placeholder an entry reads, its instructions included', () => {+ const { agents } = parseTemplateAgents(`+agent:+ name: "{team}-fixer"+ instructions: Work on {repo}.+`);+ expect(agents[0].placeholders.sort()).toEqual(['repo', 'team']);+ });+});++describe('parseTemplateAgents: managed agents', () => {+ it('counts a machine, or a machine param, as saying where an agent runs', () => {+ const { unsaid } = parseTemplateAgents(`+params:+ box: { type: machine, default: [$first] }+agents:+ - name: a+ provider: claude+ machine: laptop+ directory: /tmp/a+ instructions: A.+ - name: b+ provider: claude+ machine: "{box}"+ directory: /tmp/b+ instructions: B.+`);+ expect(unsaid).toEqual([]);+ });++ it('reads the settings a managed agent carries', () => {+ const { agents, warnings } = parseTemplateAgents(`+agent:+ name: a+ instructions: A.+ model: claude-sonnet+ advanced_config: { effort: high }+ isolation: isolated+ auto_approve: true+ connections:+ - { service: github, access: write, repos: [acme/widgets] }+ - atlassian+ - { service: linear, access: admin }+`);+ expect(agents[0]).toMatchObject({+ model: 'claude-sonnet',+ advancedConfig: { effort: 'high' },+ isolation: 'isolated',+ autoApprove: true,+ connections: [+ { service: 'github', access: 'write', repos: ['acme/widgets'] },+ { service: 'atlassian', access: null, repos: [] },+ { service: 'linear', access: null, repos: [] },+ ],+ });+ expect(warnings).toEqual(["`agent:`: linear access 'admin' is not read or write."]);+ });++ it('leaves machine params out of the room document', () => {+ const doc = load(+ serverDocument(`+params:+ box: { type: machine, default: [$first] }+ topic: { type: string }+agent:+ name: a+ instructions: A.+ machine: "{box}"+room:+ name: "{topic}"+ agents: ["{agent}"]+`) ?? ''+ ) as { params: Record<string, unknown> };+ expect(Object.keys(doc.params)).toEqual(['agent', 'topic']);+ });+});++describe('parseTemplateAgents: allow_existing', () => {+ it('lets an entry be filled by an existing agent only when the template says so', () => {+ const { agents } = parseTemplateAgents(`+agents:+ - name: reviewer+ allow_existing: true+ instructions: Review.+ - name: fixer+ instructions: Fix.+`);+ expect(agents.map((a) => a.allowExisting)).toEqual([true, false]);+ });+});++describe('version 2 documents', () => {+ const V2 = `+version: 2+params:+ start_in: { type: enum, enum: [nowhere, new_room], default: nowhere }+ room_name: { type: string, if: "{start_in} == new_room" }+resources:+ expert:+ type: agent+ display_name: Switch expert+ instructions: Help.+ provider: claude+ machine: laptop+ directory: "{$agents_dir}/{expert.name}"+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "{room_name}"+ agents: [expert]+ kickoff: "@{expert.name} hi"+`;++ it('reads agents from resources, with their key and condition', () => {+ const { agents, singular, unsaid } = parseTemplateAgents(V2);+ expect(agents.map((a) => [a.key, a.displayName, a.condition])).toEqual([+ ['expert', 'Switch expert', null],+ ]);+ expect(singular).toBe(false);+ expect(unsaid).toEqual([]);+ expect(templateKind(V2)).toBe('agent');+ });++ it('reads rooms with their key, condition and the params they read', () => {+ const { rooms } = version2Rooms(V2);+ expect(rooms).toMatchObject([+ {+ key: 'expert_room',+ condition: '{start_in} == new_room',+ agents: ['expert'],+ kickoff: '@{expert.name} hi',+ },+ ]);+ expect(rooms[0]!.placeholders).toContain('room_name');+ });++ it('writes a bundled brief into the agent resource', () => {+ const doc = load(+ composeTemplateDocument(V2.replace(' instructions: Help.\n', ''), 'Brief')+ ) as {+ resources: { expert: { instructions: string } };+ };+ expect(doc.resources.expert.instructions).toBe('Brief');+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.ts b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.tsindex 5ee401ba9..d44d3c5c2 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-document.ts@@ -29,6 +29,15 @@ import {*/export type TemplateKind = 'agent' | 'room' | 'group';+/** A connection a template grants an agent: the deployer's own connection to `service`. */+export type TemplateConnection = {+ service: string;+ /** Null for the level a new grant takes by default. */+ access: 'read' | 'write' | null;+ /** GitHub only: the repositories it reaches, `owner/name`. */+ repos: string[];+};+export type ParsedAgentEntry = {/** The name as written in the template, with any `{param}` still unfilled. */name: string | null;@@ -42,15 +51,66 @@ export type ParsedAgentEntry = {/*** Which coding agent runs it. Either a provider id (`claude`, `codex`,* `opencode`) or a `{param}` whose value is one. Null when the template- * has no `provider` field; the Use page asks for one.+ * has no `provider` field.*/provider: string | null;/** Where it runs: `local`, an ssh host, or a `{param}`. Null when the template has no `location` field. */location: string | null;+ /**+ * Where it runs as one of the owner's machines on the server: a machine's+ * name or id, or a `{param}`. Null when the template has no `machine` field.+ */+ machine: string | null;+ /** The model to run, or a `{param}`; null for the provider's default. */+ model: string | null;+ /** The provider's advanced settings, as written; `{param}`s still unfilled. */+ advancedConfig: Record<string, unknown>;+ /** `shared` or `isolated`, or a `{param}`; null for shared. */+ isolation: string | null;+ /** Run tools without asking: `true`, `false`, or a `{param}`; null for false. */+ autoApprove: boolean | string | null;+ /** The deployer's connections it is granted, as written. */+ connections: TemplateConnection[];/** Its working directory, or a `{param}`. Null when the template has no `directory` field. */directory: string | null;/** Rooms the agent is added to once it exists, by name or `{param}`. */join: string[];+ /** Every `{name}` written anywhere in the entry, its instructions included. */+ placeholders: string[];+ /**+ * Whether the deployer may fill this entry with an agent the server already+ * has instead of creating it. From `allow_existing:`, false unless the+ * template says so.+ */+ allowExisting: boolean;+ /** A version 2 resource's key; null in a version 1 document. */+ key: string | null;+ /** A version 2 resource's `if:`: created only while it holds. */+ condition: string | null;+};++/**+ * What runs an agent, where, and in which folder: what a template must say+ * for every agent it creates. Where it runs is said with `location` or+ * `machine`; `location` stands for both.+ */+export type RuntimeField = 'provider' | 'location' | 'directory';+export const RUNTIME_FIELDS: readonly RuntimeField[] = ['provider', 'location', 'directory'];++/** The fields, and param types, that say each runtime setting. */+const RUNTIME_KINDS: Record<RuntimeField, readonly string[]> = {+ provider: ['provider'],+ location: ['location', 'machine'],+ directory: ['directory'],+};++/** A runtime setting the document never gives one of its agents. */+export type UnsaidRuntime = {+ /** The index of the agent entry. */+ index: number;+ /** How the entry is named in the document, for a message. */+ label: string;+ field: RuntimeField;};export type TemplateAgents = {@@ -62,6 +122,12 @@ export type TemplateAgents = {*/singular: boolean;warnings: string[];+ /**+ * The runtime settings the document leaves unsaid. The Console supplies+ * none of its own, so the editor warns about each and the Use page refuses+ * to create until the document says it.+ */+ unsaid: UnsaidRuntime[];};const ADDRESSING_VALUES: ReadonlySet<string> = new Set(['owner', 'owner-agents', 'anyone']);@@ -85,8 +151,24 @@ function asRecord(value: unknown): Record<string, unknown> | null {: null;}+/** Whether a document is written in version 2 of the language: resources with a key and a type. */+export function isVersion2(doc: Record<string, unknown>): boolean {+ return doc.version === 2 || asRecord(doc.resources) !== null;+}++/** A version 2 document's resources of one type, with their keys. */+function resourcesOf(+ doc: Record<string, unknown>,+ type: 'agent' | 'room' | 'group'+): [string, Record<string, unknown>][] {+ return Object.entries(asRecord(doc.resources) ?? {})+ .map(([key, spec]) => [key, asRecord(spec)] as const)+ .filter((e): e is [string, Record<string, unknown>] => e[1] !== null && e[1].type === type);+}+/** The agent entries as parsed YAML objects, from `agents:` (a list) or `agent:` (a single entry). */function rawAgents(doc: Record<string, unknown>): Record<string, unknown>[] {+ if (isVersion2(doc)) return resourcesOf(doc, 'agent').map(([key, spec]) => ({ ...spec, key }));if (Array.isArray(doc.agents)) {return doc.agents.map((a) => asRecord(a)).filter((a): a is Record<string, unknown> => !!a);}@@ -104,6 +186,12 @@ export function templateKind(yamlText: string): TemplateKind {}export function kindOf(doc: Record<string, unknown>): TemplateKind {+ if (isVersion2(doc)) {+ const rooms = resourcesOf(doc, 'room').length;+ const agentCount = resourcesOf(doc, 'agent').length;+ if (resourcesOf(doc, 'group').length > 0 || rooms > 1 || agentCount > 1) return 'group';+ return agentCount === 1 ? 'agent' : 'room';+ }const agents = rawAgents(doc);if (doc.group !== undefined || Array.isArray(doc.rooms)) return 'group';if (agents.length > 1) return 'group';@@ -166,13 +254,104 @@ export function parseTemplateAgents(: null,provider: optionalString(agent.provider),location: optionalString(agent.location),+ machine: optionalString(agent.machine),+ model: optionalString(agent.model),+ advancedConfig: asRecord(agent.advanced_config) ?? {},+ isolation: optionalString(agent.isolation),+ autoApprove:+ typeof agent.auto_approve === 'boolean'+ ? agent.auto_approve+ : optionalString(agent.auto_approve),+ connections: parseConnections(agent.connections, warnings, label),directory: optionalString(agent.directory),join: Array.isArray(agent.join)? agent.join.filter((r): r is string => typeof r === 'string' && r.trim().length > 0): [],+ placeholders: [...placeholdersIn({ ...agent, key: undefined })],+ allowExisting: agent.allow_existing === true,+ key: typeof agent.key === 'string' ? agent.key : null,+ condition: typeof agent.if === 'string' ? agent.if : null,};});- return { agents, singular: !Array.isArray(doc.agents) && agents.length === 1, warnings };+ return {+ agents,+ singular: !isVersion2(doc) && !Array.isArray(doc.agents) && agents.length === 1,+ warnings,+ unsaid: unsaidRuntime(doc, agents),+ };+}++/**+ * The provider, location and directory each agent entry leaves unsaid.+ *+ * An entry says one by its own field (a literal or a `{param}`), or the+ * document says it for every agent with a param of that type that no entry's+ * field reads.+ */+function unsaidRuntime(doc: Record<string, unknown>, agents: ParsedAgentEntry[]): UnsaidRuntime[] {+ const params = asRecord(doc.params) ?? {};+ const fieldTexts = agents.flatMap((a) => runtimeFieldTexts(a));+ const appliesToAll = (field: RuntimeField) =>+ Object.entries(params).some(+ ([name, spec]) =>+ RUNTIME_KINDS[field].includes(String(asRecord(spec)?.type)) &&+ !fieldTexts.some((t) => t.includes(`{${name}}`))+ );+ const says = (agent: ParsedAgentEntry, field: RuntimeField) =>+ RUNTIME_KINDS[field].some((kind) => agent[kind as keyof ParsedAgentEntry] !== null);+ const out: UnsaidRuntime[] = [];+ agents.forEach((agent, index) => {+ const label = agent.name ?? agent.displayName ?? `agent ${index + 1}`;+ for (const field of RUNTIME_FIELDS) {+ if (!says(agent, field) && !appliesToAll(field)) out.push({ index, label, field });+ }+ });+ return out;+}++/** The texts of an entry's runtime fields, for telling whether a param is read by one. */+export function runtimeFieldTexts(+ agent: Pick<ParsedAgentEntry, 'provider' | 'location' | 'machine' | 'directory'>+): string[] {+ return [agent.provider ?? '', agent.location ?? '', agent.machine ?? '', agent.directory ?? ''];+}++const ACCESS_VALUES: ReadonlySet<string> = new Set(['read', 'write']);++function parseConnections(raw: unknown, warnings: string[], label: string): TemplateConnection[] {+ if (raw === undefined || raw === null) return [];+ if (!Array.isArray(raw)) {+ warnings.push(`${label}: \`connections:\` is a list of services.`);+ return [];+ }+ const out: TemplateConnection[] = [];+ for (const item of raw) {+ if (typeof item === 'string' && item.trim() !== '') {+ out.push({ service: item.trim(), access: null, repos: [] });+ continue;+ }+ const record = asRecord(item);+ const service = optionalString(record?.service);+ if (!record || !service) {+ warnings.push(`${label}: each connection is a service name or {service, access, repos}.`);+ continue;+ }+ const access = optionalString(record.access);+ if (access !== null && !ACCESS_VALUES.has(access)) {+ warnings.push(`${label}: ${service} access '${access}' is not read or write.`);+ }+ const repos = Array.isArray(record.repos)+ ? record.repos.filter((r): r is string => typeof r === 'string' && r.trim() !== '')+ : typeof record.repos === 'string'+ ? [record.repos]+ : [];+ out.push({+ service,+ access: access === 'read' || access === 'write' ? access : null,+ repos,+ });+ }+ return out;}/** How the Use page lays out what the template folds away. From the document's `form:` block. */@@ -206,6 +385,28 @@ export function parseAgentTemplate(fallbackInstructions: string | null = null): ParsedAgentTemplate {const doc = parseYaml(yamlText);+ if (isVersion2(doc)) {+ const { agents, warnings } = parseTemplateAgents(yamlText, fallbackInstructions);+ if (agents.length !== 1)+ throw new Error(+ 'This template creates several agents, so it has no single set of instructions to offer.'+ );+ const [agent] = agents;+ const [first] = resourcesOf(doc, 'room');+ return {+ name: agent!.name,+ addressing: agent!.addressing,+ description: agent!.description,+ instructions: agent!.instructions,+ repoUrl: agent!.repoUrl,+ sources: agent!.sources,+ room: first+ ? { name: optionalString(first[1].name), kickoff: optionalString(first[1].kickoff) }+ : null,+ provider: agent!.provider,+ warnings,+ };+ }if (asRecord(doc.agent) === null) {throw new Error(Array.isArray(doc.agents)@@ -375,7 +576,10 @@ export function substituteAgentSlots(*/export function composeTemplateDocument(yamlText: string, instructions: string): string {const doc = parseYaml(yamlText);- const entries = rawAgents(doc);+ // The resources themselves, so the brief is written into the document.+ const entries = isVersion2(doc)+ ? resourcesOf(doc, 'agent').map(([, spec]) => spec)+ : rawAgents(doc);if (entries.length === 0) throw new Error('Template must have an "agent:" block.');for (const agent of entries) {if (typeof agent.instructions !== 'string' || agent.instructions.trim().length === 0) {@@ -384,3 +588,43 @@ export function composeTemplateDocument(yamlText: string, instructions: string):}return dump(doc, { lineWidth: -1 });}++/** A version 2 document's rooms and group, as the Use page shows them. */+export type Version2Rooms = {+ rooms: {+ key: string;+ condition: string | null;+ name: string | null;+ description: string | null;+ agents: string[];+ users: string[];+ bridge: string | null;+ kickoff: string | null;+ placeholders: string[];+ }[];+ groupName: string | null;+ usesCreator: boolean;+};++export function version2Rooms(yamlText: string): Version2Rooms {+ const doc = parseYaml(yamlText);+ const strings = (value: unknown) =>+ Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];+ const rooms = resourcesOf(doc, 'room').map(([key, spec]) => ({+ key,+ condition: typeof spec.if === 'string' ? spec.if : null,+ name: optionalString(spec.name),+ description: optionalString(spec.description),+ agents: strings(spec.agents),+ users: strings(spec.users),+ bridge: optionalString(spec.bridge),+ kickoff: optionalString(spec.kickoff),+ placeholders: [...placeholdersIn(spec)],+ }));+ const [group] = resourcesOf(doc, 'group');+ return {+ rooms,+ groupName: group ? optionalString(group[1].name) : null,+ usesCreator: yamlText.includes('{$creator}'),+ };+}diff --git a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.test.ts b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.test.tsindex 9a925e88a..1419e621a 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.test.ts@@ -60,6 +60,44 @@ rooms:});});+describe('summarizeTemplate on a version 2 document', () => {+ const expert = `+version: 2+params:+ start_in: { type: enum, enum: [nowhere, new_room], default: nowhere }+ existing_room: { type: room, if: "{start_in} == existing_room" }+ topic: { type: string }+ machine: { type: machine, default: [$first] }+resources:+ expert:+ type: agent+ display_name: Switch expert+ description: Knows Switch+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: Ask the expert+`;++ it('counts what every run creates and asks, not what only some answers do', () => {+ expect(counts(summarizeTemplate(expert))).toEqual({+ kind: 'agent',+ rooms: 0,+ agents: 1,+ inputs: 1,+ });+ });++ it('lists the conditional room, saying it is created only for some answers', () => {+ const s = summarizeTemplate(expert);+ expect(s.creates.map((c) => [c.kind, c.name])).toEqual([+ ['room', 'Ask the expert'],+ ['agent', 'Switch expert'],+ ]);+ expect(s.creates[0].description).toBe('A room. Created only for some answers.');+ });+});+describe('summarizeTemplate creates', () => {it('lists rooms then agents, with the template spelling', () => {const s = summarizeTemplate(`diff --git a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.ts b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.tsindex 947a25292..58d02197c 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-templates/template-summary.ts@@ -60,6 +60,7 @@ export function summarizeTemplate(yamlText: string): TemplateSummary {doc = null;}const root = asRecord(doc) ?? {};+ if (root.version === 2) return summarizeVersion2(root);// Only params the deployer has to answer: no default to prefill from, and// not marked optional. A chain default counts as a default here, since a// server with the first candidate set up asks nothing.@@ -113,3 +114,54 @@ export function summarizeTemplate(yamlText: string): TemplateSummary {creates: roomEntries.length > 0 ? creates : [],};}++/**+ * A version 2 document says what it creates under `resources:`, each with a+ * type. A resource with an `if:` is created only for some answers, and a+ * param with one is asked only for some, so neither is counted: the card+ * says what every run creates and what every run asks.+ */+function summarizeVersion2(root: Record<string, unknown>): TemplateSummary {+ const resources = Object.entries(asRecord(root.resources) ?? {}).flatMap(([key, value]) => {+ const r = asRecord(value);+ return r ? [{ key, r }] : [];+ });+ const always = resources.filter(({ r }) => r.if === undefined);+ const ofType = (list: typeof resources, type: string) => list.filter(({ r }) => r.type === type);+ // As for version 1: params with no default to prefill from, not marked optional.+ const inputs = Object.values(asRecord(root.params) ?? {}).filter((spec) => {+ const record = asRecord(spec);+ return record?.if === undefined && record?.default === undefined && record?.required !== false;+ }).length;+ const name = (key: string, r: Record<string, unknown>) =>+ str(r.name) || str(r.display_name) || key;+ const rooms = ofType(resources, 'room');+ const agents = ofType(resources, 'agent');+ const described = (r: Record<string, unknown>, fallback: string) => {+ const text = str(r.description) || fallback;+ return r.if === undefined+ ? text+ : `${text.replace(/\.?$/, '.')} Created only for some answers.`;+ };+ const creates: TemplateEntity[] = [+ ...rooms.map(({ key, r }) => ({+ kind: 'room' as const,+ name: name(key, r),+ description: described(r, 'A room'),+ })),+ ...agents.map(({ key, r }) => ({+ kind: 'agent' as const,+ name: name(key, r),+ description: described(r, 'An agent with its own instructions'),+ })),+ ];+ const roomCount = ofType(always, 'room').length;+ const agentCount = ofType(always, 'agent').length;+ const kind =+ ofType(resources, 'group').length > 0 || roomCount > 1 || agents.length > 1+ ? 'group'+ : agents.length > 0+ ? 'agent'+ : 'room';+ return { kind, rooms: roomCount, agents: agentCount, inputs, creates };+}diff --git a/console/apps/switch-console-desktop/src/main/core/room-templates/controller.ts b/console/apps/switch-console-desktop/src/main/core/room-templates/controller.tsindex 1231c08f7..b580e4ba3 100644--- a/console/apps/switch-console-desktop/src/main/core/room-templates/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/room-templates/controller.ts@@ -37,6 +37,8 @@ export type ParamSpec = {/** Bounds of a number param, inclusive. */min: number | null;max: number | null;+ /** A version 2 param's `if:`: asked only while it holds. Null when it has none. */+ condition: string | null;};/** One room of a template, with the fields the Use page shows and edits. */@@ -47,6 +49,11 @@ export type TemplateRoom = {users: string[];bridge: string | null;kickoff: string | null;+ /** A version 2 room resource's key and `if:`; null for version 1. */+ key?: string | null;+ condition?: string | null;+ /** Every `{name}` the room reads, for telling which params only it uses. */+ placeholders?: string[];};export type ParsedTemplate = {@@ -93,6 +100,7 @@ export function extractParams(raw: unknown): ParamSpec[] {pattern: null,min: null,max: null,+ condition: null,};}const s = spec as Record<string, unknown>;@@ -123,6 +131,7 @@ export function extractParams(raw: unknown): ParamSpec[] {pattern: validType === 'string' && typeof s.pattern === 'string' ? s.pattern : null,min: validType === 'number' && typeof s.min === 'number' ? s.min : null,max: validType === 'number' && typeof s.max === 'number' ? s.max : null,+ condition: typeof s.if === 'string' ? s.if : null,};});}diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/gateway-client.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/gateway-client.tsindex 13c4c8c4a..56dac323a 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/gateway-client.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/gateway-client.ts@@ -2230,14 +2230,19 @@ export async function createRoomFromTemplate(method: 'POST',body: { yaml: yamlText, inputs, ...(templateName ? { template_name: templateName } : {}) },});- const json = (await res.json()) as- | RoomJson- | {- group_id: string;- group_name: string;- rooms?: RoomJson[];- errors?: Array<Record<string, unknown> & { error: string }>;- };+ return toProvisionResult((await res.json()) as ProvisionJson);+}++type ProvisionJson =+ | RoomJson+ | {+ group_id: string;+ group_name: string;+ rooms?: RoomJson[];+ errors?: Array<Record<string, unknown> & { error: string }>;+ };++function toProvisionResult(json: ProvisionJson): ProvisionFromTemplateResult {if ('group_id' in json) {return {kind: 'group',@@ -2250,6 +2255,171 @@ export async function createRoomFromTemplate(return { kind: 'room', ...toRoomResult(json) };}+/** One agent a template run creates, resolved by the Use page, as the server takes it. */+export type TemplateRunAgent = {+ /** How the template names it, for matching a refusal to its card. */+ slot: string;+ name: string;+ description: string;+ displayName: string | null;+ instructions: string;+ provider: string;+ /** One of the owner's machines on the server, by id or exact name. */+ machine: string;+ model: string | null;+ advancedConfig: Record<string, unknown>;+ isolation: 'shared' | 'isolated';+ autoApprove: boolean;+ /** May start with `{$agents_dir}`, the machine's own folder for agents; null for the agent's own workspace there. */+ directory: string | null;+ addressing: 'owner' | 'owner-agents' | 'anyone';+ connections: { service: string; access: 'read' | 'write' | null; repos: string[] }[];+};++/** Why one agent of a run could not be created, with the server's reason code. */+export type TemplateRunProblem = { slot: string; code: string; message: string };++export type TemplateRunResult =+ | {+ kind: 'created';+ createdAgents: {+ slot: string;+ agentId: string;+ name: string;+ machine: { id: string; name: string };+ /** False when it was not taking events before its rooms were made: the kickoff may not have reached it. */+ listening: boolean;+ }[];+ room: ProvisionFromTemplateResult | null;+ }+ | {+ /** Nothing was kept: `agents_not_created` before anything existed, or+ * `run_undone` when created agents were deleted again. */+ kind: 'refused';+ code: string;+ message: string;+ problems: TemplateRunProblem[];+ /** Agents of the run that could not be deleted again. */+ leftBehind: string[];+ };++const templateRunRefusalSchema = z.object({+ detail: z.string(),+ code: z.string(),+ problems: z+ .array(z.object({ slot: z.string(), code: z.string(), message: z.string() }))+ .optional(),+ left_behind: z.array(z.string()).optional(),+});++/**+ * Run a template that creates agents, in one request: the agents as managed+ * agents of the signed-in person on their machines, then the room half+ * (`yamlText`, naming them by name; null for no room). The server checks+ * everything first and keeps nothing when the run fails.+ */+export async function runTemplateWithAgents(+ server: SwitchServer,+ body: {+ agents: TemplateRunAgent[];+ yamlText: string | null;+ inputs: Record<string, string | number | boolean>;+ templateName: string;+ }+): Promise<TemplateRunResult> {+ return postTemplateRun(server, '/rooms/from-template', {+ agents: body.agents.map((a) => ({+ slot: a.slot,+ name: a.name,+ description: a.description,+ display_name: a.displayName,+ instructions: a.instructions,+ provider: a.provider,+ machine: a.machine,+ model: a.model,+ advanced_config: a.advancedConfig,+ isolation: a.isolation,+ auto_approve: a.autoApprove,+ directory: a.directory,+ addressing: a.addressing,+ connections: a.connections,+ })),+ yaml: body.yamlText,+ inputs: body.inputs,+ template_name: body.templateName,+ });+}++/**+ * Run a template from its document, in one request: the server works the+ * agents and rooms out of the document and the inputs (a version 2+ * document's conditions and references are the server's to resolve), checks+ * everything, and keeps nothing when the run fails.+ */+export async function runTemplateDocument(+ server: SwitchServer,+ body: {+ template: string;+ inputs: Record<string, string | number | boolean>;+ /** Existing agents standing in for slots that allow it, by resource key. */+ filled: Record<string, string>;+ templateName: string;+ }+): Promise<TemplateRunResult> {+ return postTemplateRun(server, '/rooms/from-template-document', {+ template: body.template,+ inputs: body.inputs,+ filled: body.filled,+ template_name: body.templateName,+ });+}++async function postTemplateRun(+ server: SwitchServer,+ path: string,+ body: Record<string, unknown>+): Promise<TemplateRunResult> {+ let res: Response;+ try {+ res = await gatewayFetch(server, path, { authenticated: true, method: 'POST', body });+ } catch (error) {+ if (error instanceof GatewayError && error.status === 409 && error.body) {+ const parsed = templateRunRefusalSchema.safeParse(JSON.parse(error.body));+ if (parsed.success) {+ return {+ kind: 'refused',+ code: parsed.data.code,+ message: parsed.data.detail,+ problems: parsed.data.problems ?? [],+ leftBehind: parsed.data.left_behind ?? [],+ };+ }+ }+ throw error;+ }+ const json = (await res.json()) as {+ created_agents: {+ slot: string;+ agent_id: string;+ name: string;+ machine: { id: string; name: string };+ listening: boolean;+ }[];+ room: ProvisionJson | null;+ };+ return {+ kind: 'created',+ createdAgents: json.created_agents.map((a) => ({+ slot: a.slot,+ agentId: a.agent_id,+ name: a.name,+ machine: a.machine,+ listening: a.listening,+ })),+ room: json.room === null ? null : toProvisionResult(json.room),+ };+}+// ── Template runs ───────────────────────────────────────────────────────────/** `paused` waits for its owner to continue it; `stopped` refuses further@@ -2394,8 +2564,10 @@ export type StoredTemplateSummary = {description: string;kind: string;creator: string;- /** The owner's user id, so the Console can mark the signed-in user's own templates. */+ /** The owner's user id, so the Console can mark the signed-in user's own templates. Null for one that comes with Switch. */ownerId: string | null;+ /** Comes with Switch: served by the server itself, and nobody can change or delete it. */+ official: boolean;/** Starts at 1 and goes up by one each time the document is changed. */version: number;/** `private` is seen by its owner and admins only. */@@ -2418,7 +2590,7 @@ export type StoredTemplateDetail = StoredTemplateSummary & {type RegistryTemplateSummary = {id: string;- owner_id: string;+ owner_id: string | null;owner_name: string | null;name: string;description: string;@@ -2428,6 +2600,7 @@ type RegistryTemplateSummary = {write_visibility?: TemplateVisibility;can_edit?: boolean;can_manage?: boolean;+ official?: boolean;};function toSummary(t: RegistryTemplateSummary): StoredTemplateSummary {@@ -2436,8 +2609,9 @@ function toSummary(t: RegistryTemplateSummary): StoredTemplateSummary {name: t.name,description: t.description,kind: t.kind,- creator: t.owner_name ?? t.owner_id,+ creator: t.owner_name ?? t.owner_id ?? 'Switch',ownerId: t.owner_id,+ official: t.official ?? false,// A server that does not report versions is read as being on the first.version: t.version ?? 1,// A server without visibility fields shares every template and lets itsdiff --git a/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts b/console/apps/switch-console-desktop/src/main/core/workspaces/controller.tsindex 23899bfc2..4fb1bee55 100644--- a/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts@@ -13,6 +13,10 @@ import {beginChatClaim,changeTemplateRun,createRoomFromTemplate,+ runTemplateDocument,+ runTemplateWithAgents,+ type TemplateRunAgent,+ type TemplateRunResult,createTemplate,deleteRoom,deleteTemplate,@@ -531,6 +535,34 @@ export const workspacesController = createRPCController({createRoomFromTemplate(server, yamlText, inputs, templateName)),+ /**+ * Run a template that creates agents in one request: the agents as managed+ * agents on the signed-in person's machines, then its rooms. Nothing is+ * kept when it is refused; the result says why, per agent.+ */+ runTemplateWithAgents: (+ workspaceId: string,+ body: {+ agents: TemplateRunAgent[];+ yamlText: string | null;+ inputs: Record<string, string | number | boolean>;+ templateName: string;+ }+ ): Promise<TemplateRunResult> =>+ withWorkspaceSession(workspaceId, (server) => runTemplateWithAgents(server, body)),++ /** Run a template from its document: the server works the agents and rooms out of it. */+ runTemplateDocument: (+ workspaceId: string,+ body: {+ template: string;+ inputs: Record<string, string | number | boolean>;+ filled: Record<string, string>;+ templateName: string;+ }+ ): Promise<TemplateRunResult> =>+ withWorkspaceSession(workspaceId, (server) => runTemplateDocument(server, body)),+/** The runs the user may see, or null when the server does not record runs. */listTemplateRuns: (params: { workspaceId: string }): Promise<TemplateRun[] | null> =>withWorkspaceSession(params.workspaceId, fetchTemplateRuns),diff --git a/console/apps/switch-console-desktop/src/renderer/features/room-templates/room-template-import-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/room-templates/room-template-import-view.tsxindex ab68221b5..e17cd0c74 100644--- a/console/apps/switch-console-desktop/src/renderer/features/room-templates/room-template-import-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/room-templates/room-template-import-view.tsx@@ -12,6 +12,7 @@ import {type TemplateAccess,visibilityOf,} from '@renderer/features/templates/template-visibility';+import { unsaidMessage } from '@renderer/features/templates/use/use-template-model';import { workspacesStore } from '@renderer/features/workspaces/workspaces-store';import { failureText } from '@renderer/lib/errors/describe-failure';import { toast } from '@renderer/lib/hooks/use-toast';@@ -24,7 +25,6 @@ import { Button } from '@renderer/lib/ui/button';import { Field, FieldGroup, FieldLabel } from '@renderer/lib/ui/field';import { Input } from '@renderer/lib/ui/input';import { SegmentedControl } from '@renderer/lib/ui/segmented-control';-import { StepPager } from '@renderer/lib/ui/step-pager';// ── Source step ─────────────────────────────────────────────────────────────@@ -40,22 +40,23 @@ function SourceStep({yamlText,onYamlChange,parseError,+ warnings,onNext,canAdvance,onFileSelect,- onSaveToServer,saving,editing,}: {yamlText: string;onYamlChange: (text: string) => void;parseError: string | null;+ /** What the document leaves unsaid. Advice only: saving goes ahead regardless. */+ warnings: string[];onNext: () => void;/** Whether there is a document to go on with. Decided by the page, so the* Next button and the pager's arrow cannot come to different answers. */canAdvance: boolean;onFileSelect: (name: string) => void;- onSaveToServer: () => void;saving: boolean;/** Set when the document belongs to a stored template: the actions become Cancel and Save changes. */editing?: { onCancel: () => void; onSave: () => void; canSave: boolean };@@ -164,6 +165,23 @@ function SourceStep({</Alert>)}+ {warnings.length > 0 && (+ <Alert>+ <AlertDescription>+ <div className="flex flex-col gap-1.5">+ <span>+ This template can be saved, but nothing can be created from it until it says:+ </span>+ <ul className="list-disc pl-4">+ {warnings.map((w) => (+ <li key={w}>{w}</li>+ ))}+ </ul>+ </div>+ </AlertDescription>+ </Alert>+ )}+{editing ? (<div className="flex items-center justify-end gap-2 pt-2"><Button variant="outline" disabled={saving} onClick={editing.onCancel}>@@ -176,12 +194,8 @@ function SourceStep({</div>) : (<div className="flex items-center justify-end gap-2 pt-2">- <Button variant="outline" disabled={!yamlText.trim() || saving} onClick={onSaveToServer}>- <Save className="mr-1.5 size-3.5" />- {saving ? 'Saving…' : 'Save to workspace'}- </Button><Button disabled={!canAdvance} onClick={onNext}>- Next+ {saving ? 'Importing…' : 'Import'}<ArrowRight className="ml-1.5 size-3.5" /></Button></div>@@ -227,7 +241,6 @@ const TemplateImportPanel = observer(function TemplateImportPanel() {yamlText: initialYaml,sourceName: initialName,templateId: initialTemplateId,- edit: editing,editingTemplate,} = useParams('templateImport').params;const [yamlText, setYamlText] = useState(initialYaml ?? '');@@ -237,41 +250,49 @@ const TemplateImportPanel = observer(function TemplateImportPanel() {const [name, setName] = useState(editingTemplate?.name ?? '');const [description, setDescription] = useState(editingTemplate?.description ?? '');const [access, setAccess] = useState<TemplateAccess>(editingTemplate?.access ?? 'shared');+ const [warnings, setWarnings] = useState<string[]>([]);- // Parse before navigating so a syntax error is shown next to the editor,- // where it can be fixed, rather than on the Use page.- const handleParseAndAdvance = useCallback(async () => {- setParseError(null);- try {- await rpc.agentTemplates.parseAgents({ yamlText });- const coreYaml = await rpc.agentTemplates.serverDocument({ yamlText });- if (coreYaml) await rpc.roomTemplates.parse({ yamlText: coreYaml });- else if ((await rpc.agentTemplates.parseAgents({ yamlText })).agents.length === 0) {- throw new Error('Template must have a "room:", "group:" or "agent:" block.');- }- appState.navigation.navigate('templateUse', {- serverId,- yamlText,- sourceName: sourceName ?? undefined,- });- } catch (e) {- setParseError(failureText(e, 'Could not parse this template.'));- }- }, [yamlText, serverId, sourceName]);+ // What the document leaves unsaid, checked as it is typed. A document that+ // does not parse yet has nothing to say here; its error is shown when it is+ // saved or used.+ useEffect(() => {+ let cancelled = false;+ const timer = window.setTimeout(() => {+ rpc.agentTemplates+ .parseAgents({ yamlText })+ .then(({ unsaid }) => {+ if (!cancelled) setWarnings(unsaid.map(unsaidMessage));+ })+ .catch(() => {+ if (!cancelled) setWarnings([]);+ });+ }, 300);+ return () => {+ cancelled = true;+ window.clearTimeout(timer);+ };+ }, [yamlText]);- // Save the document to the workspace without using it. The dialog asks for- // the name and description, prefilled from the document.+ // Import is saving: every template lives on the workspace, and is used from+ // there. The document is checked first, so a syntax error shows by the+ // editor; the dialog asks for the name and description, prefilled from it.const handleSaveToServer = useCallback(async () => {setSaving(true);setParseError(null);try {+ await rpc.agentTemplates.parseAgents({ yamlText });+ if ((await rpc.agentTemplates.kind({ yamlText })) === 'room') {+ const coreYaml = await rpc.agentTemplates.serverDocument({ yamlText });+ if (coreYaml) await rpc.roomTemplates.parse({ yamlText: coreYaml });+ }const prefill = await prefillForSave(yamlText, sourceName);showModal('saveTemplateModal', {serverId,serverName: switchServersStore.servers.find((sv) => sv.id === serverId)?.name ?? null,content: yamlText,...prefill,- onSuccess: () => appState.navigation.navigate('templates', { serverId }),+ onSuccess: ({ id }) =>+ appState.navigation.navigate('templateDetail', { serverId, templateId: id }),});} catch (e) {setParseError(failureText(e, 'Could not read this template.'));@@ -327,13 +348,7 @@ const TemplateImportPanel = observer(function TemplateImportPanel() {appState.navigation.navigate('templateUse', { serverId, templateId: initialTemplateId });return;}- // `edit` is set when the deployer came back from the Use page to change- // the document, so it must not be sent on again.- if (initialYaml && initialYaml.trim().length > 0 && !editing) {- advancedOnce.current = true;- void handleParseAndAdvance();- }- }, [initialTemplateId, initialYaml, editing, serverId, handleParseAndAdvance]);+ }, [initialTemplateId, serverId]);// The pager's arrow only repeats the Next button below, so both read this// rather than spelling the condition once each and drifting apart.@@ -388,10 +403,10 @@ const TemplateImportPanel = observer(function TemplateImportPanel() {yamlText={yamlText}onYamlChange={setYamlText}parseError={parseError}- onNext={handleParseAndAdvance}+ warnings={warnings}+ onNext={() => void handleSaveChanges()}canAdvance={canAdvance}onFileSelect={setSourceName}- onSaveToServer={handleSaveToServer}saving={saving}editing={{onCancel: () =>@@ -412,23 +427,16 @@ const TemplateImportPanel = observer(function TemplateImportPanel() {<ServerPagewidth={896}title="Import a template"- description="Paste an agent, room or group template, or pick a YAML file. The document says which it is."- footer={- <StepPager- pageName="Pick a template"- onBack={null}- onNext={canAdvance ? () => void handleParseAndAdvance() : null}- />- }+ description="Paste a template or pick a YAML file. It is saved on this workspace, and used from there like every other template."><SourceStepyamlText={yamlText}onYamlChange={setYamlText}parseError={parseError}- onNext={handleParseAndAdvance}+ warnings={warnings}+ onNext={() => void handleSaveToServer()}canAdvance={canAdvance}onFileSelect={setSourceName}- onSaveToServer={handleSaveToServer}saving={saving}/></ServerPage>diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsxindex b3c2c0a6d..c93392189 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx@@ -4,8 +4,6 @@ import { useCallback, useEffect, useState } from 'react';import type { StoredTemplateSummary } from '@main/core/switch-servers/gateway-client';import { agentsStore } from '@renderer/features/locations/stores/agents-store';import { switchRoomsStore } from '@renderer/features/switch-servers/switch-rooms-store';-import { switchServersStore } from '@renderer/features/switch-servers/switch-servers-store';-import { bundledTemplates } from '@renderer/features/templates/bundled-templates';import { workspacesStore } from '@renderer/features/workspaces/workspaces-store';import { agentProviderLabel } from '@renderer/lib/components/agent-mark';import { AgentPickerRow, ChosenAgentTile } from '@renderer/lib/components/agent-picker';@@ -49,9 +47,7 @@ export const AddAgentsToRoomModal = observer(function AddAgentsToRoomModal({const serverId = workspaceId === null ? null : workspacesStore.serverIdFor(workspaceId);const roomName = switchRoomsStore.roomNameById(roomId);- // Templates can create an agent straight into this room. The bundled- // templates are listed at once; the workspace's are added when the request- // returns.+ // Templates can create an agent straight into this room.const [serverTemplates, setServerTemplates] = useState<StoredTemplateSummary[]>([]);useEffect(() => {if (workspaceId === null) return;@@ -66,7 +62,6 @@ export const AddAgentsToRoomModal = observer(function AddAgentsToRoomModal({setServerTemplates([]);toast({title: failureText(e, "Could not load the workspace's templates."),- description: 'The built-in ones are still offered.',variant: 'destructive',});});@@ -74,33 +69,7 @@ export const AddAgentsToRoomModal = observer(function AddAgentsToRoomModal({cancelled = true;};}, [workspaceId]);- // A built-in template the signed-in user saved to the workspace is listed- // once, as their copy. Names are unique only per owner, so someone else's- // template of the same name is not a copy.- const meId = serverId ? (switchServersStore.statusFor(serverId)?.user?.id ?? null) : null;- const onWorkspace = serverTemplates.filter((t) => t.kind === 'agent');- const templates: StoredTemplateSummary[] = [- ...bundledTemplates- .filter(- (b) =>- b.kind === 'agent' &&- !onWorkspace.some((t) => t.name === b.name && meId !== null && t.ownerId === meId)- )- .map(({ id, name, description, kind, creator }) => ({- id,- name,- description,- kind,- creator,- ownerId: null,- version: 1,- readVisibility: 'public' as const,- writeVisibility: 'private' as const,- canEdit: false,- canManage: false,- })),- ...onWorkspace,- ];+ const templates = serverTemplates.filter((t) => t.kind === 'agent');// The Use page creates the agent. With `intoRoomId` it adds the agent to// this room instead of creating the template's own room.const createFromTemplate = (template: StoredTemplateSummary) => {diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/agent-template-data.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/agent-template-data.tsindex 67af9d2e8..55d03e7e2 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/agent-template-data.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/agent-template-data.ts@@ -5,8 +5,9 @@ import type { AgentTemplateOrigin } from '@main/core/agents/agent-config-file';import type { ParsedTemplate } from '@main/core/room-templates/controller';import type { StoredTemplateSummary } from '@main/core/switch-servers/gateway-client';import { workspacesStore } from '@renderer/features/workspaces/workspaces-store';+import { failureText } from '@renderer/lib/errors/describe-failure';import { rpc } from '@renderer/lib/ipc';-import { type BundledTemplate, bundledTemplates, findBundledTemplate } from './bundled-templates';+import { bundledYamlFor, findBundledTemplate } from './bundled-templates';/*** One agent as a template describes it, plus its room part already converted@@ -60,7 +61,8 @@ export async function agentTemplateFromContent(}/** Whether the template recorded on an agent's config can still be loaded.- * A bundled template can be dropped from a later Console. */+ * An agent made before templates came from the server records a template+ * bundled with the Console, which a later Console can drop. */export function templateOriginExists(origin: AgentTemplateOrigin): boolean {return origin.source !== 'bundled' || findBundledTemplate(origin.id) !== undefined;}@@ -72,7 +74,12 @@ export async function loadAgentTemplateByOrigin(if (origin.source === 'bundled') {const bundled = findBundledTemplate(origin.id);if (!bundled) throw new Error(`This Console no longer bundles "${origin.name}".`);- return agentTemplateFromContent(origin.name, bundled.yamlText, bundled.instructions, origin);+ return agentTemplateFromContent(+ origin.name,+ await bundledYamlFor(bundled, origin.serverId ?? null),+ bundled.instructions,+ origin+ );}const detail = await rpc.workspaces.getTemplateDetail({workspaceId: templateWorkspaceId(origin),@@ -102,19 +109,11 @@ function templateWorkspaceId(origin: AgentTemplateOrigin): string {);}-/** Resolve a listing entry (bundled or from the server's registry) into the agent it describes. */+/** Resolve a listing entry into the agent it describes. */export async function loadAgentTemplate(workspaceId: string,template: StoredTemplateSummary): Promise<AgentTemplate> {- const bundled = findBundledTemplate(template.id);- if (bundled) {- return agentTemplateFromContent(bundled.name, bundled.yamlText, bundled.instructions, {- id: bundled.id,- name: bundled.name,- source: 'bundled',- });- }const detail = await rpc.workspaces.getTemplateDetail({ workspaceId, templateId: template.id });const serverId = workspacesStore.serverIdFor(workspaceId);return agentTemplateFromContent(detail.name, detail.definition, null, {@@ -126,19 +125,13 @@ export async function loadAgentTemplate(});}-/** A template loaded for its page: its source, what it creates, and its document. */+/** A template loaded for its page: its record, what it creates, and its document. */export type LoadedTemplate = {name: string;description: string;kind: TemplateKind;- /** The bundled template, when this is one. Null for a workspace template. */- bundled: BundledTemplate | null;- /** For a bundled template: its copy saved on the workspace, or null when there is none. */- savedCopy: StoredTemplateSummary | null;- /** For a workspace template: the bundled template with the same name, or null when there is none. */- copyOf: BundledTemplate | null;- /** The workspace record, when the template is stored on the server. Null for a bundled template. */- server: StoredTemplateSummary | null;+ /** The workspace's record of it. */+ server: StoredTemplateSummary;/** The agents the template creates, in document order. Empty for a room template. */agents: ParsedAgentEntry[];/** The room part, parsed: the rooms and the params. Null when the document has no rooms. */@@ -147,75 +140,45 @@ export type LoadedTemplate = {summary: TemplateSummary;/** The full document with agent instructions inlined, as stored or as it would be stored. */document: string;+ /** Why the document cannot be read, when it cannot. The page still opens, so it can be edited or deleted. */+ problem: string | null;};-/**- * Load one template by the id the listing gave it: a bundled id, or a registry- * row id. A bundled template also records whether the signed-in user saved a- * copy of it on the workspace, and a workspace row of theirs records which- * built-in it copies, so the page can say either. Names are unique only per- * owner, so someone else's template of the same name is not a copy.- */+/** Load one template by the id the listing gave it. */export async function loadTemplateById(workspaceId: string,- templateId: string,- meId: string | null+ templateId: string): Promise<LoadedTemplate> {- const bundled = findBundledTemplate(templateId);- let name: string;- let description: string;- let document: string;- let server: StoredTemplateSummary | null = null;- let copyOf: BundledTemplate | null = null;- let savedCopy: StoredTemplateSummary | null = null;- if (bundled) {- savedCopy =- (await rpc.workspaces.listTemplates({ workspaceId }).catch(() => [])).find(- (t) => t.name === bundled.name && meId !== null && t.ownerId === meId- ) ?? null;- name = bundled.name;- description = bundled.description;- document = bundled.instructions- ? await rpc.agentTemplates.compose({- yamlText: bundled.yamlText,- instructions: bundled.instructions,- })- : bundled.yamlText;- } else {- const detail = await rpc.workspaces.getTemplateDetail({ workspaceId, templateId });- const { definition, ...summary } = detail;- name = detail.name;- description = detail.description;- document = definition;- server = summary;- copyOf =- meId !== null && detail.ownerId === meId- ? (bundledTemplates.find((b) => b.name === detail.name) ?? null)- : null;- }- const kind = await rpc.agentTemplates.kind({ yamlText: document });- const { agents } = await rpc.agentTemplates.parseAgents({ yamlText: document });- // Every param, the Console's own types included, so the Inputs table lists- // what the Use page asks for and what the card counts.- const coreYaml = await rpc.agentTemplates.serverDocument({- yamlText: document,- keepConsoleParams: true,- });- const room = coreYaml ? await rpc.roomTemplates.parse({ yamlText: coreYaml }) : null;+ const detail = await rpc.workspaces.getTemplateDetail({ workspaceId, templateId });+ const { definition: document, ...server } = detail;+ const { name, description } = detail;const summary = await rpc.agentTemplates.summarize({ yamlText: document });- return {- name,- description,- kind,- bundled: bundled ?? null,- savedCopy,- copyOf,- server,- agents,- room,- summary,- document,- };+ try {+ const kind = await rpc.agentTemplates.kind({ yamlText: document });+ const { agents } = await rpc.agentTemplates.parseAgents({ yamlText: document });+ // Every param, the Console's own types included, so the Inputs table lists+ // what the Use page asks for and what the card counts.+ const coreYaml = await rpc.agentTemplates.serverDocument({+ yamlText: document,+ keepConsoleParams: true,+ });+ const room = coreYaml ? await rpc.roomTemplates.parse({ yamlText: coreYaml }) : null;+ return { name, description, kind, server, agents, room, summary, document, problem: null };+ } catch (e) {+ const kind: TemplateKind =+ server.kind === 'agent' || server.kind === 'group' ? server.kind : 'room';+ return {+ name,+ description,+ kind,+ server,+ agents: [],+ room: null,+ summary: { ...summary, creates: [] },+ document,+ problem: failureText(e, 'Its document could not be read.'),+ };+ }}/** A readable listing name from a file name: no extension, no `.template`, words not dashes. */diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/bundled-templates.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/bundled-templates.tsindex 95f49e2b7..7edd917c9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/bundled-templates.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/bundled-templates.ts@@ -1,4 +1,6 @@+import { rpc } from '@renderer/lib/ipc';import switchExpertInstructions from '@root/../../../switch-expert/AGENT.md?raw';+import switchExpertConsoleTemplate from '@root/../../../switch-expert/template.console.yaml?raw';import switchExpertTemplate from '@root/../../../switch-expert/template.yaml?raw';/**@@ -14,7 +16,13 @@ export type BundledTemplate = {description: string;kind: string;creator: string;+ /** The document for a server that runs agent management. */yamlText: string;+ /**+ * The document for a server that does not, which the Console runs the+ * agents of itself; null when the template has only the one.+ */+ yamlWithoutManagement: string | null;/** Instructions kept in a separate file, used when the document has no `instructions:`. */instructions: string | null;};@@ -23,10 +31,12 @@ export const bundledTemplates: BundledTemplate[] = [{id: 'bundled:switch-expert',name: 'Switch expert',- description: 'Knows Switch inside out. Ask it how to set things up or why something is off.',+ description:+ 'An agent that knows Switch inside out. Ask it how to set things up or why something is off.',kind: 'agent',creator: 'Switch',yamlText: switchExpertTemplate,+ yamlWithoutManagement: switchExpertConsoleTemplate,instructions: switchExpertInstructions,},];@@ -34,3 +44,20 @@ export const bundledTemplates: BundledTemplate[] = [export function findBundledTemplate(id: string): BundledTemplate | undefined {return bundledTemplates.find((t) => t.id === id);}++/**+ * The bundled document to use on a server: the one for agent management when+ * the server runs it (its `agent_management` feature flag), else the one the+ * Console runs the agents of itself.+ */+export async function bundledYamlFor(+ template: BundledTemplate,+ serverId: string | null+): Promise<string> {+ if (template.yamlWithoutManagement === null) return template.yamlText;+ if (serverId === null) return template.yamlWithoutManagement;+ const res = await rpc.featureFlags.get(serverId);+ return res?.success && res.data.flags.agent_management+ ? template.yamlText+ : template.yamlWithoutManagement;+}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/template-detail-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/template-detail-view.tsxindex 6560ed31b..d4afb7349 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/template-detail-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/template-detail-view.tsx@@ -2,6 +2,7 @@ import {ArrowLeft,Bot,Check,+ CircleAlert,Copy,DoorOpen,Download,@@ -22,6 +23,7 @@ import { toast } from '@renderer/lib/hooks/use-toast';import { rpc } from '@renderer/lib/ipc';import { useNavigate, useParams } from '@renderer/lib/layout/navigation-provider';import { openExternalUrl } from '@renderer/lib/open-external';+import { Alert, AlertDescription } from '@renderer/lib/ui/alert';import { Badge } from '@renderer/lib/ui/badge';import { Button } from '@renderer/lib/ui/button';import { DisclosureRow } from '@renderer/lib/ui/disclosure-row';@@ -163,7 +165,7 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {const [loaded, setLoaded] = useState<LoadedTemplate | null>(null);const [error, setError] = useState<string | null>(null);- const [busy, setBusy] = useState<'save' | 'delete' | 'export' | null>(null);+ const [busy, setBusy] = useState<'delete' | 'export' | null>(null);const [confirmRemove, setConfirmRemove] = useState(false);const [showDocument, setShowDocument] = useState(false);const [showInstructions, setShowInstructions] = useState(false);@@ -180,7 +182,7 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {let cancelled = false;setLoaded(null);setError(null);- loadTemplateById(workspaceId, templateId, me?.id ?? null)+ loadTemplateById(workspaceId, templateId).then((t) => {if (cancelled) return;setLoaded(t);@@ -193,7 +195,7 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {cancelled = true;setCurrentName(null);};- }, [workspaceId, templateId, me?.id]);+ }, [workspaceId, templateId]);const back = (<Button@@ -224,14 +226,14 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {);}- const mine = loaded.server !== null && me !== null && loaded.server.ownerId === me.id;+ const official = loaded.server.official;+ const mine = !official && me !== null && loaded.server.ownerId === me.id;// The server says what this user may do: it knows who administers the// workspace, which the user's global role does not tell. An older server// leaves the answer out, and the owner-or-admin guess stands in.- const canManage =- loaded.server !== null && (loaded.server.canManage ?? (mine || me?.role === 'admin'));+ const canManage = !official && (loaded.server.canManage ?? (mine || me?.role === 'admin'));const canEdit =- loaded.server !== null &&+ !official &&(loaded.server.canEdit ?? (canManage || loaded.server.writeVisibility === 'public'));const singleAgent = loaded.kind === 'agent' ? (loaded.agents[0] ?? null) : null;// In a single-agent document the room refers to the agent as `{agent}`. The@@ -241,32 +243,8 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {const use = () => navigate('templateUse', { serverId, templateId });- const saveToServer = async () => {- if (!loaded.bundled || workspaceId === null) return;- setBusy('save');- try {- const saved = await rpc.workspaces.saveTemplate({- workspaceId,- name: loaded.bundled.name,- description: loaded.bundled.description,- kind: loaded.bundled.kind,- content: loaded.document,- });- toast({ title: `"${loaded.name}" is now on ${server?.name ?? 'the workspace'}` });- navigate('templateDetail', { serverId, templateId: saved.id });- } catch (e) {- toast({- title: 'Could not save the template to the workspace',- description: failureText(e, 'Check the server connection and try again.'),- variant: 'destructive',- });- } finally {- setBusy(null);- }- };-const remove = async () => {- if (!loaded.server || workspaceId === null) return;+ if (workspaceId === null) return;setBusy('delete');try {await rpc.workspaces.deleteTemplate({ workspaceId, templateId: loaded.server.id });@@ -302,14 +280,12 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {}};- const ownerLine = loaded.bundled- ? 'Shipped with Switch'+ const ownerLine = official+ ? 'Comes with Switch': mine? 'Yours'- : `Uploaded by ${loaded.server?.creator ?? 'someone'}`;- const visibilityLine = loaded.server- ? accessLine(accessOf(loaded.server))- : 'Shared with everyone';+ : `Uploaded by ${loaded.server.creator}`;+ const visibilityLine = accessLine(accessOf(loaded.server));return (<div className="relative z-10 flex min-h-0 flex-1 flex-col overflow-auto bg-background">@@ -324,32 +300,12 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {<span>{ownerLine}</span><span>·</span><span>{visibilityLine}</span>- {loaded.server && loaded.server.version > 1 && (+ {loaded.server.version > 1 && (<><span>·</span><span>Version {loaded.server.version}</span></>)}- {loaded.copyOf && (- <>- <span>·</span>- <span>A copy of the built-in one</span>- </>- )}- {loaded.savedCopy && (- <>- <span>·</span>- <button- type="button"- className="cursor-pointer underline underline-offset-2 hover:text-foreground"- onClick={() =>- navigate('templateDetail', { serverId, templateId: loaded.savedCopy!.id })- }- >- A copy is saved on this workspace- </button>- </>- )}</span></span>}@@ -357,24 +313,13 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {><div className="flex flex-wrap items-center gap-2"><Badge variant="secondary">{KIND_LABEL[loaded.kind]}</Badge>- {loaded.bundled && (- <Badge variant="outline" title="Shipped with Switch">+ {official && (+ <Badge variant="outline" title="Comes with Switch">Official</Badge>)}<span className="flex-1" />- {loaded.bundled && !loaded.savedCopy && (- <Button- type="button"- variant="outline"- size="sm"- disabled={busy !== null}- onClick={() => void saveToServer()}- >- {busy === 'save' ? 'Saving…' : 'Save to workspace'}- </Button>- )}- {canEdit && loaded.server && (+ {canEdit && (<Buttontype="button"variant="outline"@@ -386,11 +331,11 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {yamlText: loaded.document,edit: true,editingTemplate: {- id: loaded.server!.id,+ id: loaded.server.id,name: loaded.name,description: loaded.description,- kind: loaded.server!.kind,- access: accessOf(loaded.server!),+ kind: loaded.server.kind,+ access: accessOf(loaded.server),canChangeAccess: canManage,},})@@ -423,12 +368,29 @@ const TemplateDetailPanel = observer(function TemplateDetailPanel() {: 'Remove from workspace'}</Button>)}- <Button type="button" size="sm" onClick={use} disabled={busy !== null}>+ <Button+ type="button"+ size="sm"+ onClick={use}+ disabled={busy !== null || loaded.problem !== null}+ >Use template</Button></div></PageHeader>+ {loaded.problem && (+ <Alert variant="destructive">+ <CircleAlert />+ <AlertDescription>+ This template cannot be used. {loaded.problem}{' '}+ {canEdit || canManage+ ? 'Edit it to fix the document, or remove it.'+ : 'Ask whoever saved it to fix it.'}+ </AlertDescription>+ </Alert>+ )}+<section className="flex flex-col gap-2.5"><h2 className="text-sm font-semibold text-foreground">What it creates</h2>{loaded.summary.creates.length > 0 ? (diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs-list.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs-list.tsxdeleted file mode 100644index 2c892784b..000000000--- a/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs-list.tsx+++ /dev/null@@ -1,197 +0,0 @@-import { Boxes, DoorOpen, Play, Square } from 'lucide-react';-import { useCallback, useEffect, useRef, useState } from 'react';-import type { TemplateRun } from '@main/core/switch-servers/gateway-client';-import { openRoom } from '@renderer/features/switch-rooms/open-room';-import { failureText } from '@renderer/lib/errors/describe-failure';-import { toast } from '@renderer/lib/hooks/use-toast';-import { rpc } from '@renderer/lib/ipc';-import { Button } from '@renderer/lib/ui/button';-import { StatusBadge } from '@renderer/lib/ui/status-badge';-import { formatTimeAgo, isLiveRun, runAuthor, runLabel } from './template-runs';--/** How often shown runs are asked for again while one of them can still change. */-const LIVE_RUN_POLL_MS = 15_000;--/**- * The runs the server records for this workspace, loaded when the listing- * opens and again when the window regains focus, and polled while any of- * them is running or paused.- *- * Quiet on failure: an older server without runs answers 404 and the list- * stays empty, and a failed refresh keeps what was already shown.- */-export function useTemplateRuns(workspaceId: string | null): {- runs: TemplateRun[];- replace: (run: TemplateRun) => void;-} {- const [runs, setRuns] = useState<TemplateRun[]>([]);- // An answer that lands after the listing moved to another workspace- // belongs to the old one and is dropped.- const shownWorkspace = useRef(workspaceId);- shownWorkspace.current = workspaceId;-- const load = useCallback(async () => {- if (workspaceId === null) return;- try {- const list = await rpc.workspaces.listTemplateRuns({ workspaceId });- if (shownWorkspace.current === workspaceId) setRuns(list ?? []);- } catch {- // The runs are an addition to the recents; the section renders without them.- }- }, [workspaceId]);-- useEffect(() => {- setRuns([]);- void load();- const onFocus = () => void load();- window.addEventListener('focus', onFocus);- return () => window.removeEventListener('focus', onFocus);- }, [load]);-- const live = runs.some(isLiveRun);- useEffect(() => {- if (!live) return;- const timer = setInterval(() => {- if (document.hidden) return;- void load();- }, LIVE_RUN_POLL_MS);- return () => clearInterval(timer);- }, [live, load]);-- const replace = useCallback(- (run: TemplateRun) =>- setRuns((prev) => prev.map((r) => (r.rootRoomId === run.rootRoomId ? run : r))),- []- );-- return { runs, replace };-}--/** The columns every row of Recently used shares, runs and documents alike:- * name, status, size, when, and one action slot. */-export const RECENT_ROW =- 'grid grid-cols-[minmax(0,1fr)_6.5rem_4.5rem_4.5rem_11rem] items-center gap-x-3 px-3 py-1.5 min-h-10 text-sm';--/** The one button style of the action column. */-export const RECENT_ACTION = 'h-7 px-2.5 text-xs';--function RunState({ run }: { run: TemplateRun }) {- if (run.state === 'paused')- return (- <span title={run.reason ?? undefined}>- <StatusBadge tone="warning">Paused</StatusBadge>- </span>- );- if (run.state === 'stopped') return <StatusBadge tone="neutral">Stopped</StatusBadge>;- if (!run.working) return null;- return (- <span className="inline-flex items-center gap-1.5 text-xs text-foreground-muted">- <span className="size-1.5 animate-pulse rounded-full bg-emerald-500" />- Working- </span>- );-}--/**- * One run in "Recently used", in the shared columns: what it came from and- * who made its rooms, its state, how many rooms, when it last moved, and- * Continue or Stop when something can still happen in it. The name opens the- * room the run started from.- */-export function TemplateRunRow({- workspaceId,- run,- onChanged,-}: {- workspaceId: string;- run: TemplateRun;- onChanged: (run: TemplateRun) => void;-}) {- const [busy, setBusy] = useState<'stop' | 'continue' | null>(null);- const [confirmStop, setConfirmStop] = useState(false);- const Icon = run.rooms.length > 1 ? Boxes : DoorOpen;- const rooms = run.rooms.length;- const paused = run.state === 'paused';- const canStop = run.canControl && (paused || (run.state === 'running' && run.working));-- const change = async (action: 'stop' | 'continue') => {- setBusy(action);- try {- const params = { workspaceId, rootRoomId: run.rootRoomId };- onChanged(- action === 'stop'- ? await rpc.workspaces.stopTemplateRun(params)- : await rpc.workspaces.continueTemplateRun(params)- );- } catch (error) {- toast({- title:- action === 'stop'- ? `Could not stop "${runLabel(run)}"`- : `Could not continue "${runLabel(run)}"`,- description: failureText(error, 'The server did not accept the change.'),- variant: 'destructive',- });- } finally {- setBusy(null);- setConfirmStop(false);- }- };-- return (- <div className={RECENT_ROW}>- <button- type="button"- onClick={() => void openRoom(run.rootRoomId)}- className="flex min-w-0 cursor-pointer items-center gap-2 text-left hover:underline"- >- <Icon className="size-3.5 shrink-0 text-foreground-muted" />- <span className="truncate">{runLabel(run)}</span>- <span className="shrink-0 text-xs text-foreground-passive">{runAuthor(run)}</span>- </button>- <span>- <RunState run={run} />- </span>- <span className="text-xs text-foreground-passive">- {rooms} {rooms === 1 ? 'room' : 'rooms'}- </span>- <span className="text-xs text-foreground-passive">- {formatTimeAgo(Date.parse(run.lastActivityAt))}- </span>- <span className="flex justify-end gap-1.5">- {run.canControl && paused && (- <Button- type="button"- variant="outline"- size="sm"- className={RECENT_ACTION}- disabled={busy !== null}- onClick={() => void change('continue')}- >- <Play className="size-3.5" />- {busy === 'continue' ? 'Continuing…' : 'Continue'}- </Button>- )}- {canStop && (- <Button- type="button"- variant="outline"- size="sm"- className={RECENT_ACTION}- disabled={busy !== null}- title="Agents can no longer create rooms in this run. The rooms stay."- onClick={() => {- // A stopped run cannot be started again, so the first click asks.- if (confirmStop) void change('stop');- else setConfirmStop(true);- }}- onBlur={() => setConfirmStop(false)}- >- <Square className="size-3.5" />- {busy === 'stop' ? 'Stopping…' : confirmStop ? 'Sure?' : 'Stop'}- </Button>- )}- </span>- </div>- );-}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs.tsdeleted file mode 100644index 46ef769c3..000000000--- a/console/apps/switch-console-desktop/src/renderer/features/templates/template-runs.ts+++ /dev/null@@ -1,47 +0,0 @@-import type { TemplateRun } from '@main/core/switch-servers/gateway-client';--export function formatTimeAgo(ms: number): string {- const seconds = Math.floor((Date.now() - ms) / 1000);- if (seconds < 60) return 'just now';- const minutes = Math.floor(seconds / 60);- if (minutes < 60) return `${minutes}m ago`;- const hours = Math.floor(minutes / 60);- if (hours < 24) return `${hours}h ago`;- return `${Math.floor(hours / 24)}d ago`;-}--/** What a run is listed as: the template it came from, else its first room. */-export function runLabel(run: TemplateRun): string {- return run.templateName ?? run.rootRoomName;-}--/**- * Who made the run's rooms, for the row's "by" line. The agents that created- * rooms in it, by name, or whoever started it when no agent has: a run with- * only its root room is a template someone ran.- */-export function runAuthor(run: TemplateRun): string {- const names: string[] = [];- for (const room of run.rooms) {- const name = room.createdByAgentName;- if (room.createdByAgentId !== null && name && !names.includes(name)) names.push(name);- }- if (names.length === 0) return run.startedByName ?? 'someone';- if (names.length === 1) return names[0];- return `${names[0]} and ${names.length - 1} more`;-}--/** Whether the run can still change, so its row is worth refreshing: an idle- * run starts working again when someone addresses an agent in its rooms. */-export function isLiveRun(run: TemplateRun): boolean {- return run.state === 'running' || run.state === 'paused';-}--/** Whether the run matches the listing's search text, by its label or any room name. */-export function runMatches(run: TemplateRun, needle: string): boolean {- if (needle.length === 0) return true;- return (- runLabel(run).toLowerCase().includes(needle) ||- run.rooms.some((r) => r.name.toLowerCase().includes(needle))- );-}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/template-use-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/template-use-view.tsxindex ed3e4f144..280e50ca8 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/template-use-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/template-use-view.tsx@@ -5,12 +5,18 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';import type {FormOptions,ParsedAgentEntry,+ TemplateConnection,TemplateKind,+ UnsaidRuntime,} from '@main/core/agent-templates/template-document';import type { AgentTemplateOrigin } from '@main/core/agents/agent-config-file';import type { ParamSpec, ParsedTemplate } from '@main/core/room-templates/controller';+import type {+ ProvisionFromTemplateResult,+ TemplateRunResult,+} from '@main/core/switch-servers/gateway-client';import type { GuardResult, ViewDefinition } from '@renderer/app/view-registry';-import { AgentTypePicker } from '@renderer/features/locations/components/add-agent-modal/agent-type-picker';+import { machineLabel } from '@renderer/features/locations/components/add-agent-modal/server-run-locations';import { agentsStore } from '@renderer/features/locations/stores/agents-store';import { HostReachabilityNotice } from '@renderer/features/remote-hosts/host-reachability-notice';import { hostReachabilityStore } from '@renderer/features/remote-hosts/host-reachability-store';@@ -44,6 +50,7 @@ import { Button } from '@renderer/lib/ui/button';import { Switch } from '@renderer/lib/ui/switch';import { cn } from '@renderer/utils/utils';import { AGENT_NAME_PATTERN, slugifyAgentNamePart } from '@shared/core/agents/agent-slug';+import type { OwnedMachine } from '@shared/core/managed-agents/managed-agents';import {type AgentProviderId,isValidProviderId,@@ -53,7 +60,6 @@ import { describeRemoteDirRefusal } from '@shared/core/remote-hosts/remote-dir';import { ownerAndMyAgentsPolicy, ownerOnlyPolicy } from '@shared/core/switch-servers/owner-policy';import { NEW } from '@shared/core/switch-servers/room-template-params';import { RpcError } from '@shared/lib/ipc/rpc-error';-import { findBundledTemplate } from './bundled-templates';import { CollapsibleInput } from './use/collapsible-input';import {type AgentSlot,@@ -61,10 +67,20 @@ import {newSlot,ResolvedDocument,RoomCard,- SlotDirectoryField,type SlotStatus,} from './use/creates-rail';import { CreatingScreen } from './use/creating-screen';+import {+ connectionStates,+ connectionsFor,+ directoryUnresolved,+ machineFor,+ machineProblem,+ managedDirectory,+ runAgent,+ runtimeFieldTexts,+ shownDirectory,+} from './use/managed-run';import { ParamField } from './use/param-field';import { RoomChoiceField } from './use/room-pick-field';import { LOCAL_RUN_LOCATION, runLocationLabel, useAllowedHosts } from './use/run-location-select';@@ -75,6 +91,7 @@ import {createStepStatus,defaultsFor,hasPlaceholder,+ holds,interpolate,isChain,isEmpty,@@ -82,8 +99,9 @@ import {paramLabel,placeholdersIn,resolveChain,- sectionOf,+ roomOnlyParams,serverInputs,+ unsaidMessage,type Values,valueProblem,} from './use/use-template-model';@@ -121,36 +139,33 @@ type UsePageTemplate = {parsed: ParsedTemplate | null;coreYaml: string | null;warnings: string[];+ /** The provider, location and directory the document never gives an agent. */+ unsaid: UnsaidRuntime[];+ /** 2 for a document of resources with a key and a type, whose run the server works out. */+ version: 1 | 2;};async function loadUsePageTemplate(workspaceId: string, params: Params): Promise<UsePageTemplate> {let name: string;let yamlText: string;- let instructions: string | null = null;+ // A document from the server has its instructions written in.+ const instructions: string | null = null;let origin: AgentTemplateOrigin | null = null;if (params.templateId) {- const bundled = findBundledTemplate(params.templateId);- if (bundled) {- name = bundled.name;- yamlText = bundled.yamlText;- instructions = bundled.instructions;- origin = { id: bundled.id, name: bundled.name, source: 'bundled' };- } else {- const detail = await rpc.workspaces.getTemplateDetail({- workspaceId,- templateId: params.templateId,- });- name = detail.name;- yamlText = detail.definition;- const serverId = workspacesStore.serverIdFor(workspaceId);- origin = {- id: detail.id,- name: detail.name,- source: 'server',- workspaceId,- ...(serverId ? { serverId } : {}),- };- }+ const detail = await rpc.workspaces.getTemplateDetail({+ workspaceId,+ templateId: params.templateId,+ });+ name = detail.name;+ yamlText = detail.definition;+ const serverId = workspacesStore.serverIdFor(workspaceId);+ origin = {+ id: detail.id,+ name: detail.name,+ source: 'server',+ workspaceId,+ ...(serverId ? { serverId } : {}),+ };} else if (params.yamlText) {name = params.sourceName?.replace(/(\.template)?\.ya?ml$/i, '') ?? 'Pasted template';yamlText = params.yamlText;@@ -158,10 +173,48 @@ async function loadUsePageTemplate(workspaceId: string, params: Params): Promisethrow new Error('Nothing to use: no template was given.');}const kind = await rpc.agentTemplates.kind({ yamlText });- const { agents, singular, warnings } = await rpc.agentTemplates.parseAgents({+ const { agents, singular, warnings, unsaid } = await rpc.agentTemplates.parseAgents({yamlText,instructions,});+ const v2 = await rpc.agentTemplates.version2Rooms({ yamlText });+ if (v2) {+ // The server works out a version 2 run from the document itself; the page+ // only reads what it shows: the params, the agents and the rooms.+ const v2Params = await rpc.roomTemplates.params({ yamlText });+ const first = v2.rooms[0] ?? null;+ return {+ name,+ yamlText,+ instructions,+ origin,+ kind,+ agents,+ singular: false,+ params: v2Params,+ serverParamNames: new Set(v2Params.map((p) => p.name)),+ form: await rpc.agentTemplates.form({ yamlText }),+ parsed: {+ params: v2Params,+ rooms: v2.rooms,+ groupName: v2.groupName,+ roomName: first?.name ?? null,+ roomDescription: first?.description ?? null,+ agents: [...new Set(v2.rooms.flatMap((r) => r.agents))],+ hardcodedAgents: [],+ hardcodedUsers: [],+ users: [...new Set(v2.rooms.flatMap((r) => r.users))],+ bridge: first?.bridge && !first.bridge.includes('{') ? first.bridge : null,+ kickoff: first?.kickoff ?? null,+ usesCreator: v2.usesCreator,+ warnings: [],+ },+ coreYaml: null,+ warnings,+ unsaid,+ version: 2,+ };+ }// Two versions of the room document: one that keeps every param, for// building the form, and one with only what the server understands.const forForm = await rpc.agentTemplates.serverDocument({ yamlText, keepConsoleParams: true });@@ -191,6 +244,8 @@ async function loadUsePageTemplate(workspaceId: string, params: Params): Promiseparsed,coreYaml,warnings: [...warnings, ...(parsed?.warnings ?? [])],+ unsaid,+ version: 1,};}@@ -208,15 +263,6 @@ const TemplateUseTitlebar = observer(function TemplateUseTitlebar() {);});-function SectionTitle({ title, hint }: { title: string; hint?: string }) {- return (- <div className="flex flex-col gap-1">- <h3 className="text-sm font-semibold text-foreground">{title}</h3>- {hint && <p className="text-[12.5px] leading-relaxed text-foreground-muted">{hint}</p>}- </div>- );-}-/** A value the template fixed: shown so nothing is hidden, not editable. */function FixedRow({ label, value }: { label: string; value: string }) {return (@@ -234,15 +280,33 @@ function FixedRow({ label, value }: { label: string; value: string }) {type SlotSetup = {/** The identifier the agent is created under. */name: string;+ /** Set when the deployer fills the entry with an existing agent, which the+ * template allows with `allow_existing`: its name, empty while none is picked. */+ existing: string | null;displayName: string | null;provider: AgentProviderId | null;- /** `local`, or an SSH host. */- location: string;+ /** `local`, or an SSH host. Null when nothing in the template says. */+ location: string | null;directory: string;+ /**+ * On a server with agent management, every new agent is a managed agent on+ * one of the deployer's machines: the one its `machine` names, or the one+ * behind its `location`. Null when it names none of them, or for an+ * existing agent, or without agent management.+ */+ machine: OwnedMachine | null;+ /** The `machine` the template gives it, filled in; null when it gives none. */+ machineText: string | null;+ /** The directory sent for a managed agent, `{$agents_dir}` kept for the server. */+ managedDirectory: string;+ /** The deployer's connections it is granted, its `repo` folded in. */+ connections: TemplateConnection[];/** Rooms the agent joins once it exists, by name. */joins: string[];/** Whether the run creates the template's room for it. */makesRoom: boolean;+ /** False for a version 2 agent whose `if:` does not hold: the run does not create it. */+ on: boolean;};const TemplateUsePanel = observer(function TemplateUsePanel() {@@ -259,9 +323,6 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {const [slots, setSlots] = useState<AgentSlot[]>([]);const [editedAgents, setEditedAgents] = useState<string[]>([]);const [editedUsers, setEditedUsers] = useState<string[]>([]);- // The provider for agents whose template names none and declares no- // `provider` param: asked on the page, never chosen for the deployer.- const [pickedProvider, setPickedProvider] = useState<AgentProviderId | null>(null);const [phase, setPhase] = useState<'form' | 'creating' | 'done' | 'failed'>('form');const [doneDetail, setDoneDetail] = useState<string | null>(null);// What the server returned for the room, kept so that a step failing after@@ -311,7 +372,6 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {setRoomOn(false);setPickingRoom(false);nameStepped.current = false;- setPickedProvider(null);setSlots(result.agents.map(newSlot));// The editable member list holds the room's fixed agents that the template// does not create. Agents it creates have their own cards.@@ -330,57 +390,76 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {const parsed = loaded?.parsed ?? null;// In the singular `agent:` form the room refers to the agent as `{agent}`.// The page fills that in with the agent's name, so it is not an input.- const templateParams = useMemo(- () => (loaded?.params ?? []).filter((p) => !(loaded?.singular && p.name === 'agent')),- [loaded]+ const isV2 = loaded?.version === 2;+ // A version 2 room is made only while its `if:` holds.+ const roomsOn = useMemo(+ () => (isV2 ? (parsed?.rooms ?? []).filter((r) => holds(r.condition, values)) : []),+ [isV2, parsed, values]);+ const templateParams = useMemo(() => {+ const base = (loaded?.params ?? []).filter((p) => !(loaded?.singular && p.name === 'agent'));+ if (!isV2 || !loaded) return base;+ // A version 2 param is asked while its `if:` holds, and while something+ // that is made reads it: one only an unmade room reads asks nothing.+ return base.filter((p) => {+ if (!holds(p.condition, values)) return false;+ const rooms = (parsed?.rooms ?? []).filter((r) => r.placeholders?.includes(p.name));+ const agents = loaded.agents.filter((a) => a.placeholders.includes(p.name));+ if (rooms.length + agents.length === 0) return true;+ return (+ rooms.some((r) => holds(r.condition, values)) ||+ agents.some((a) => holds(a.condition, values))+ );+ });+ }, [loaded, isV2, parsed, values]);const createsAgents = (loaded?.agents.length ?? 0) > 0;- const hasRoomPart = loaded?.coreYaml !== null && parsed !== null && !intoRoomId;- const isGroupDoc = (parsed?.rooms.length ?? 0) > 1 || (parsed?.groupName ?? null) !== null;- const templateRoom = parsed?.rooms[0] ?? null;+ const hasRoomPart = isV2+ ? roomsOn.length > 0 && !intoRoomId+ : loaded?.coreYaml !== null && parsed !== null && !intoRoomId;+ const isGroupDoc = isV2+ ? roomsOn.length > 1 || (parsed?.groupName ?? null) !== null+ : (parsed?.rooms.length ?? 0) > 1 || (parsed?.groupName ?? null) !== null;+ const templateRoom = isV2 ? (roomsOn[0] ?? null) : (parsed?.rooms[0] ?? null);- // ── Which section each param belongs to ─────────────────────────────────- const agentTexts = useMemo(- () =>- (loaded?.agents ?? []).map((a) => [- a.name ?? '',- a.displayName ?? '',- a.provider ?? '',- a.location ?? '',- a.directory ?? '',- ...a.join,- ]),- [loaded]- );+ // The params only the room reads. They do nothing, and are not shown, when the room is not made.const roomText = loaded?.coreYaml ?? '';- const sections = useMemo(- () => new Map(templateParams.map((p) => [p.name, sectionOf(p, agentTexts, roomText)])),- [templateParams, agentTexts, roomText]+ const roomOnly = useMemo(+ () => roomOnlyParams(templateParams, loaded?.agents ?? [], roomText),+ [templateParams, loaded, roomText]+ );+ // The agent entry a param is read by, for a control that depends on where+ // that agent runs. A Console-type param no entry reads applies to every+ // agent, and the first one stands for them.+ const agentIndexOf = useCallback(+ (param: ParamSpec) =>+ Math.max(+ 0,+ (loaded?.agents ?? []).findIndex((a) => a.placeholders.includes(param.name))+ ),+ [loaded]);- const paramsOfAgent = (i: number) =>- templateParams.filter((p) => {- const s = sections.get(p.name);- return s?.section === 'agent' && s.index === i;- });- const roomParams = templateParams.filter((p) => sections.get(p.name)?.section === 'room');// The `room` param an agent joins, when the template leaves the room to the deployer.const joinParam =- templateParams.find(- (p) => p.type === 'room' && (loaded?.agents ?? []).some((a) => a.join.includes(`{${p.name}}`))- ) ?? null;+ (!isV2 &&+ templateParams.find(+ (p) =>+ p.type === 'room' && (loaded?.agents ?? []).some((a) => a.join.includes(`{${p.name}}`))+ )) ||+ null;const joinValue = joinParam ? String(values[joinParam.name] ?? '') : '';// A chain that resolved to a room switches the room on.useEffect(() => {if (joinValue !== '' && !roomOn) setRoomOn(true);}, [joinValue, roomOn]);- // A Console-type param no agent entry binds applies to every agent.+ // A Console-type param no agent entry's field reads applies to every agent.+ const fieldTexts = (loaded?.agents ?? []).flatMap((a) => runtimeFieldTexts(a));const unboundOfType = (type: ParamSpec['type']) =>templateParams.find(- (p) =>- p.type === type && !agentTexts.some((texts) => texts.some((t) => t.includes(`{${p.name}}`)))+ (p) => p.type === type && !fieldTexts.some((t) => t.includes(`{${p.name}}`))) ?? null;const providerParam = unboundOfType('provider');const locationParam = unboundOfType('location');+ const machineParam = unboundOfType('machine');const directoryParam = unboundOfType('directory');// ── Server lists (pickers, identities, bridges) ─────────────────────────@@ -400,6 +479,24 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {queryFn: () => rpc.workspaces.listExternalUsers(workspaceId as string),enabled: workspaceId !== null,});+ // The deployer's machines; null when the server does not run agent+ // management, which leaves agents to be created the way Console runs them.+ const machinesQuery = useQuery({+ queryKey: ['template-use-machines', serverId, workspaceId],+ queryFn: () => rpc.managedAgents.machines(serverId),+ enabled: workspaceId !== null && (loaded?.agents.length ?? 0) > 0,+ refetchInterval: (query) => (query.state.data ? 5000 : false),+ });+ const machines = machinesQuery.data ?? null;+ const management = machines !== null;+ const wantsConnections = (loaded?.agents ?? []).some(+ (a) => a.connections.length > 0 || a.repoUrl !== null+ );+ const connectionsQuery = useQuery({+ queryKey: ['template-use-connections', workspaceId],+ queryFn: () => rpc.workspaces.getServiceConnections(workspaceId as string),+ enabled: workspaceId !== null && management && wantsConnections,+ });const { identities, refresh: refreshIdentities } = useMyIdentities(workspaceId);const bridges = useMemo(() => bridgesQuery.data ?? [], [bridgesQuery.data]);const allowedHosts = useAllowedHosts(serverId);@@ -468,64 +565,133 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {);// ── The agents: what each is made of, from the inputs ───────────────────+ // A version 2 template names each agent by its key: `{expert.name}` is the+ // name the `expert` resource is created under.+ const namedValues = useMemo((): Values => {+ if (!isV2) return values;+ const named: Values = { ...values };+ for (const slot of slots) {+ const entry = slot.entry;+ if (!entry.key) continue;+ const existing = entry.allowExisting && slot.mode === 'existing' ? slot.existingName : null;+ named[`${entry.key}.name`] =+ existing ||+ (entry.name+ ? interpolate(entry.name, values)+ : slugifyAgentNamePart(interpolate(entry.displayName ?? '', values)));+ }+ return named;+ }, [isV2, values, slots]);const setups: SlotSetup[] = useMemo(() => {+ const vals = namedValues;const roomJoinParam = (entry: ParsedAgentEntry) =>templateParams.find((p) => p.type === 'room' && entry.join.includes(`{${p.name}}`)) ?? null;return slots.map((slot) => {const entry = slot.entry;- const name = entry.name- ? interpolate(entry.name, values)- : slugifyAgentNamePart(interpolate(entry.displayName ?? '', values));- const displayName = entry.displayName ? interpolate(entry.displayName, values) : null;+ const existing = entry.allowExisting && slot.mode === 'existing' ? slot.existingName : null;+ const name =+ existing ??+ (entry.name+ ? interpolate(entry.name, vals)+ : slugifyAgentNamePart(interpolate(entry.displayName ?? '', vals)));+ const displayName = entry.displayName ? interpolate(entry.displayName, vals) : null;+ // What runs it, where, and in which folder come from the template alone:+ // its own field, else a param of that type that applies to every agent.const providerText = entry.provider- ? interpolate(entry.provider, values)+ ? interpolate(entry.provider, vals): providerParam- ? String(values[providerParam.name] ?? '')- : (pickedProvider ?? '');+ ? String(vals[providerParam.name] ?? '')+ : '';const provider: AgentProviderId | null = isValidProviderId(providerText)? providerText: null;const locationText = entry.location- ? interpolate(entry.location, values)+ ? interpolate(entry.location, vals): locationParam- ? String(values[locationParam.name] ?? '')- : LOCAL_RUN_LOCATION;- const location = locationText === '' ? LOCAL_RUN_LOCATION : locationText;- const agentsDir = agentsDirs[location] ?? '';- const dirValues: Values = { ...values, agent: name, $agents_dir: agentsDir };+ ? String(vals[locationParam.name] ?? '')+ : '';+ const location = locationText === '' || hasPlaceholder(locationText) ? null : locationText;+ const agentsDir = location !== null ? (agentsDirs[location] ?? '') : '';+ const dirValues: Values = { ...vals, agent: name, $agents_dir: agentsDir };// A directory read from a param is interpolated twice: once to reach// the param's value, once for the `{$agents_dir}` and `{agent}` inside it.- const directory = slot.dirPicked- ? slot.dir- : entry.directory- ? interpolate(interpolate(entry.directory, dirValues), dirValues)- : directoryParam- ? interpolate(String(values[directoryParam.name] ?? ''), dirValues)- : agentsDir && name && !hasPlaceholder(name)- ? `${agentsDir}/${name}`- : '';+ const directoryText = entry.directory+ ? interpolate(interpolate(entry.directory, dirValues), dirValues)+ : directoryParam+ ? interpolate(String(vals[directoryParam.name] ?? ''), dirValues)+ : '';+ const directory = hasPlaceholder(directoryText) ? '' : directoryText;const joinParam = roomJoinParam(entry);const joins = entry.join- .map((j) => interpolate(j, values))+ .map((j) => interpolate(j, vals)).filter((j) => j !== '' && j !== NEW && !hasPlaceholder(j));- const makesRoom =- hasRoomPart && (joinParam === null ? true : String(values[joinParam.name] ?? '') === NEW);- return { name, displayName, provider, location, directory, joins, makesRoom };+ const makesRoom = isV2+ ? hasRoomPart+ : hasRoomPart && (joinParam === null ? true : String(vals[joinParam.name] ?? '') === NEW);+ const machineRaw = entry.machine+ ? interpolate(entry.machine, vals)+ : machineParam+ ? String(vals[machineParam.name] ?? '')+ : '';+ const machineText = machineRaw === '' || hasPlaceholder(machineRaw) ? null : machineRaw;+ // On a server with agent management, where an agent runs is one of the+ // deployer's machines there. A `location` (this computer, an SSH host)+ // is this Console's idea, so it names a machine only when it is one;+ // otherwise the first online machine that can run the agent stands in.+ const machine =+ existing === null && machines !== null+ ? machineText !== null+ ? machineFor(machines, machineText, provider, false)+ : machineFor(machines, location, provider, location !== null)+ : null;+ const directorySource = entry.directory+ ? entry.directory+ : directoryParam+ ? String(vals[directoryParam.name] ?? '')+ : '';+ return {+ name,+ existing,+ displayName,+ provider,+ location,+ directory,+ machine,+ machineText,+ managedDirectory: managedDirectory(directorySource, vals, name),+ connections: connectionsFor(entry, vals),+ joins,+ makesRoom,+ on: !isV2 || holds(entry.condition, vals),+ };});}, [slots,- values,+ namedValues,+ isV2,templateParams,providerParam,locationParam,+ machineParam,directoryParam,- pickedProvider,agentsDirs,hasRoomPart,+ machines,]);// A room template with no agents still makes its room.const makesRoom = hasRoomPart && (setups.length === 0 || setups.some((s) => s.makesRoom));- const locations = useMemo(() => [...new Set(setups.map((s) => s.location))], [setups]);+ // The machines new agents run on.+ const locations = useMemo(+ () => [+ ...new Set(+ setups+ .filter((s) => s.existing === null && !management)+ .map((s) => s.location)+ .filter((l): l is string => l !== null)+ ),+ ],+ [setups, management]+ );const firstRemote = locations.find((l) => l !== LOCAL_RUN_LOCATION) ?? null;const hostReachable = locations.every((l) => l === LOCAL_RUN_LOCATION || !hostReachabilityStore.isBlocked(l)@@ -535,19 +701,11 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {setups.find((s) => s.location === firstRemote)?.provider ?? null);const hostReady = firstRemote === null || (!hostReadiness.blocked && !hostReadiness.checking);- // A location the server does not allow falls back to this computer.- useEffect(() => {- if (!locationParam) return;- const v = String(values[locationParam.name] ?? '');- if (v !== '' && v !== LOCAL_RUN_LOCATION && !allowedHosts.some((h) => h.sshHost === v)) {- setValues((prev) => ({ ...prev, [locationParam.name]: LOCAL_RUN_LOCATION }));- }- }, [allowedHosts, locationParam, values]);// `{$agents_dir}` for every location in play, fetched once each.useEffect(() => {for (const location of locations) {- if (agentsDirs[location] !== undefined) continue;+ if (management || agentsDirs[location] !== undefined) continue;const sshHost = location === LOCAL_RUN_LOCATION ? null : location;if (sshHost && hostReachabilityStore.isBlocked(sshHost)) continue;void rpc.agentTemplates@@ -555,7 +713,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {.then((dir) => setAgentsDirs((prev) => ({ ...prev, [location]: dir }))).catch(() => {});}- }, [locations, agentsDirs]);+ }, [locations, agentsDirs, management]);// ── Chains: each decided once its candidates are known ──────────────────const availability = useAgentTypeAvailability(firstRemote ?? undefined);@@ -571,14 +729,28 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {candidates = agents.data?.map((a) => a.name).sort();} else if (param.type === 'room') {candidates = roomsQuery.data?.map((r) => r.name).sort();- } else if (param.type === 'location') {+ } else if (param.type === 'location' && !management) {candidates = [LOCAL_RUN_LOCATION, ...allowedHosts.map((h) => h.sshHost)];+ } else if (param.type === 'machine' || param.type === 'location') {+ // Online machines first: `$first` is the first that can take an agent now.+ candidates = machinesQuery.data+ ? [...machinesQuery.data]+ .sort(+ (a, b) =>+ Number(b.state === 'online') - Number(a.state === 'online') ||+ a.name.localeCompare(b.name)+ )+ .map((m) => m.id)+ : machinesQuery.data === null+ ? []+ : undefined;} else if (param.type === 'provider') {// The providers installed where the agent reading this param runs.- const section = sections.get(param.name);- const at = section?.section === 'agent' ? setups[section.index] : undefined;+ const at = setups[agentIndexOf(param)];const list =- at && at.location !== LOCAL_RUN_LOCATION ? availability.data : localAvailability.data;+ at && at.location !== null && at.location !== LOCAL_RUN_LOCATION+ ? availability.data+ : localAvailability.data;candidates = list?.filter((a) => a.available && isValidProviderId(a.agentId)).map((a) => a.agentId);@@ -592,7 +764,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {}, [loaded,templateParams,- sections,+ agentIndexOf,setups,hasRoomPart,bridgesQuery.data,@@ -601,6 +773,8 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {allowedHosts,availability.data,localAvailability.data,+ machinesQuery.data,+ management,]);// ── Names: taken, invalid, or still unresolved ──────────────────────────@@ -643,10 +817,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {// ── Why Create is disabled ──────────────────────────────────────────────// A room's own params matter only when the room is made.- const liveParams = templateParams.filter(- (p) =>- makesRoom || joinParam === null || p === joinParam || sections.get(p.name)?.section !== 'room'- );+ const liveParams = templateParams.filter((p) => makesRoom || !roomOnly.has(p.name));const missing = missingParams(liveParams, values);const invalid = liveParams.map((p) => ({ p, problem: valueProblem(p, values[p.name] ?? '') }))@@ -657,9 +828,12 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {const seenNames = new Set<string>();slots.forEach((slot, i) => {const setup = setups[i];- if (slot.mode === 'existing') {- if (slot.existingName === '')- slotProblems.push(`Pick the existing agent for ${setup.name || `agent ${i + 1}`}.`);+ if (!setup.on) return;+ if (setup.existing !== null) {+ if (setup.existing === '')+ slotProblems.push(+ `Pick the existing agent for ${slot.entry.name ? interpolate(slot.entry.name, values) : `agent ${i + 1}`}.`+ );return;}const name = slot.createdName ?? setup.name;@@ -682,8 +856,56 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {if (param) clashErrors[param.name] = message;}seenNames.add(name);- if (!setup.provider) slotProblems.push(`Choose which coding agent runs ${name}.`);- if (setup.directory.trim() === '') slotProblems.push(`Choose a directory for ${name}.`);+ // A setting the template never gives is the template's to fix, not the+ // deployer's: the form adds no input of its own for it.+ const unsaid = loaded?.unsaid.filter((u) => u.index === i) ?? [];+ for (const u of unsaid) slotProblems.push(unsaidMessage(u));+ const says = (field: UnsaidRuntime['field']) => !unsaid.some((u) => u.field === field);+ if (says('provider') && !setup.provider)+ slotProblems.push(`Choose which coding agent runs ${name}.`);+ if (management) {+ // A managed agent: the server checks all of this again, whole, before+ // creating anything; the form says it first.+ if (says('location') && setup.machine === null)+ slotProblems.push(+ setup.machineText !== null+ ? `${setup.machineText} is not one of your machines on this server.`+ : setup.location !== null+ ? `None of your machines on this server can run ${name} now. ${+ (machines ?? [])+ .map((m) => machineProblem(m, setup.provider, name) ?? '')+ .join(' ') || 'You have no machine there yet.'+ }`+ : `Choose which machine ${name} runs on.`+ );+ else if (setup.machine !== null) {+ const problem = machineProblem(setup.machine, setup.provider, name);+ if (problem) slotProblems.push(problem);+ }+ if (+ says('directory') &&+ (setup.managedDirectory.trim() === '' || directoryUnresolved(setup.managedDirectory))+ )+ slotProblems.push(`Choose a directory for ${name}.`);+ for (const c of connectionStates(setup.connections, connectionsQuery.data ?? null)) {+ if (!c.ready && c.note) slotProblems.push(`${name}: ${c.note}`);+ }+ } else {+ if (setup.machineText !== null || slot.entry.connections.length > 0)+ slotProblems.push(+ `This server does not run agent management, so ${name} cannot be placed on a machine${slot.entry.connections.length > 0 ? ' or granted connections' : ''}.`+ );+ if (says('location') && setup.location === null)+ slotProblems.push(`Choose which machine ${name} runs on.`);+ else if (+ setup.location !== null &&+ setup.location !== LOCAL_RUN_LOCATION &&+ !allowedHosts.some((h) => h.sshHost === setup.location)+ )+ slotProblems.push(`${setup.location} is not a machine this Console can run agents on.`);+ if (says('directory') && setup.directory.trim() === '')+ slotProblems.push(`Choose a directory for ${name}.`);+ }for (const room of setup.joins) {if (roomsQuery.data && !roomsQuery.data.some((r) => r.name === room))slotProblems.push(`There is no room called ${room} on this server.`);@@ -691,7 +913,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {});if (joinParam && roomOn && joinValue === '')slotProblems.push('Pick the room, or switch it off.');- const newSlots = slots.filter((s) => s.mode === 'new');+ const newSlots = slots.filter((_, i) => setups[i]?.existing === null && setups[i]?.on);const remoteLabel = firstRemote ? runLocationLabel(firstRemote, allowedHosts) : '';const blockedReason: string | null =phase !== 'form'@@ -702,28 +924,30 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {? `Fill in ${missing.map(paramLabel).join(', ')}`: invalid.length > 0? `${paramLabel(invalid[0].p)}: ${invalid[0].problem}`- : slotProblems.length > 0- ? slotProblems[0]- : newSlots.length > 0 && !hostReachable- ? `${remoteLabel} cannot be reached right now.`- : newSlots.length > 0 && !hostReady- ? hostReadiness.checking- ? `Checking what ${remoteLabel} has installed…`- : `${remoteLabel} is missing setup the agents need.`- : !makesRoom- ? null // no room is made, so nothing below applies- : creatorBlocked- ? 'Link your messaging account first.'- : parsed !== null && noMessagingApp && parsed.usesCreator- ? 'This server has no messaging app, so the room would have no chat.'- : null;- const stillNeeded =- missing.length > 0- ? `${missing.length} input${missing.length === 1 ? '' : 's'} still needed`- : slotProblems.length > 0 || invalid.length > 0- ? `${slotProblems.length + invalid.length} thing${slotProblems.length + invalid.length === 1 ? '' : 's'} to settle`- : 'Every input filled in';-+ : isV2 && newSlots.length > 0 && machinesQuery.data === null+ ? 'This template creates managed agents, and this server does not run agent management.'+ : newSlots.length > 0 && machinesQuery.isError+ ? failureText(+ machinesQuery.error,+ 'Your machines on this server could not be listed.'+ )+ : newSlots.length > 0 && machinesQuery.data === undefined+ ? 'Checking your machines on this server…'+ : slotProblems.length > 0+ ? slotProblems[0]+ : newSlots.length > 0 && !hostReachable+ ? `${remoteLabel} cannot be reached right now.`+ : newSlots.length > 0 && !hostReady+ ? hostReadiness.checking+ ? `Checking what ${remoteLabel} has installed…`+ : `${remoteLabel} is missing setup the agents need.`+ : !makesRoom+ ? null // no room is made, so nothing below applies+ : creatorBlocked+ ? 'Link your messaging account first.'+ : !isV2 && parsed !== null && noMessagingApp && parsed.usesCreator+ ? 'This server has no messaging app, so the room would have no chat.'+ : null;// Existing agents in the room whose addressing policy blocks messages from// another member. New agents get the template's addressing at creation.const handoffBlocked = useMemo(() => {@@ -735,10 +959,9 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {if (typeof v === 'string' && v !== '') names.add(v);}}- for (const slot of slots)- if (slot.mode === 'existing' && slot.existingName) names.add(slot.existingName);+ for (const setup of setups) if (setup.existing) names.add(setup.existing);return blockedHandoffs((agents.data ?? []).filter((a) => names.has(a.name)));- }, [parsed, editedAgents, templateParams, values, slots, agents.data]);+ }, [parsed, editedAgents, templateParams, values, setups, agents.data]);const [allowingHandoffs, setAllowingHandoffs] = useState(false);const allowHandoffs = useCallback(async () => {if (workspaceId === null) return;@@ -781,6 +1004,319 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {const setSlot = (i: number, patch: Partial<AgentSlot>) =>setSlots((prev) => prev.map((s, j) => (j === i ? { ...s, ...patch } : s)));+ /** The room half as the server provisions it: agent names swapped for the+ * names the agents have, and the inputs it takes. */+ const roomRequest = async (+ templateCoreYaml: string,+ template: ParsedTemplate+ ): Promise<{ coreYaml: string; inputs: Record<string, string | number | boolean> }> => {+ const replacements: Record<string, string> = {};+ slots.forEach((slot, i) => {+ const expression = slot.entry.name ?? '';+ const actual = setups[i].existing ?? slot.createdName ?? setups[i].name;+ if (expression && actual && expression !== actual) replacements[expression] = actual;+ });+ let coreYaml = await rpc.agentTemplates.substituteSlots({+ coreYaml: templateCoreYaml,+ replacements,+ });+ if (!isGroupDoc) {+ // The member lists are rebuilt from the parsed template, so the renamed+ // agents must be renamed here too, or the original names would come back.+ const slotNamesSet = new Set(slots.map((s) => s.entry.name ?? ''));+ const keep = (list: string[]) =>+ list+ .filter((a) => hasPlaceholder(a) || slotNamesSet.has(a))+ .map((a) => replacements[a] ?? a);+ coreYaml = await rpc.roomTemplates.rewriteYaml({+ yamlText: coreYaml,+ agents: [...new Set([...keep(template.agents), ...editedAgents])],+ users: [...keep(template.users), ...editedUsers],+ });+ }+ const inputs = serverInputs(+ templateParams,+ values,+ loaded?.serverParamNames ?? new Set<string>()+ );+ if (loaded?.singular && slots.length === 1) {+ // The singular `agent:` form: the server fills `{agent}` from this input.+ inputs.agent = setups[0].existing ?? slots[0].createdName ?? setups[0].name;+ }+ return { coreYaml, inputs };+ };++ /**+ * On a server with agent management: the new agents and the room in one+ * request, which the server checks whole and keeps nothing of when it+ * fails. Records what was created, and the room in `createdRoom`, so the+ * steps after it (joins, opening the room) run as for any run. False when+ * it was refused, each reason shown on its agent's card.+ */+ /** The last run was refused whole, or undone: nothing it made is left, so there is nothing to retry from. */+ const [nothingKept, setNothingKept] = useState(false);+ // That refusal named each agent's reason, which its step shows.+ const [refusedPerAgent, setRefusedPerAgent] = useState(false);++ const createManaged = async (+ created: { slotIndex: number; name: string; switchAgentId: string | null }[]+ ): Promise<boolean> => {+ if (!loaded || workspaceId === null) return false;+ const pending = slots+ .map((slot, i) => ({ slot, i, setup: setups[i] }))+ .filter(({ slot, setup }) => setup.existing === null && slot.status !== 'created');+ const agentsToCreate = pending.map(({ slot, setup }) => {+ if (setup.machine === null || setup.provider === null)+ throw new Error(`${setup.name} has no machine or provider.`);+ return runAgent({+ slot: setup.name,+ name: setup.name,+ entry: slot.entry,+ values,+ displayName:+ setup.displayName && setup.displayName.trim() !== setup.name+ ? setup.displayName.trim()+ : null,+ provider: setup.provider,+ machine: setup.machine,+ directoryText: setup.managedDirectory,+ });+ });+ setNothingKept(false);+ setRefusedPerAgent(false);+ for (const { i } of pending) setSlot(i, { status: 'creating', error: null, step: 'create' });+ const room =+ makesRoom && loaded.coreYaml && parsed && !createdRoom.current+ ? await roomRequest(loaded.coreYaml, parsed)+ : null;+ if (room) setRoomStatus('creating');+ let result: TemplateRunResult;+ try {+ result = await rpc.workspaces.runTemplateWithAgents(workspaceId, {+ agents: agentsToCreate,+ yamlText: room?.coreYaml ?? null,+ inputs: room?.inputs ?? {},+ templateName: loaded.name,+ });+ } catch (e) {+ for (const { i } of pending) setSlot(i, { status: 'failed', step: null });+ if (room) setRoomStatus('failed');+ const serverDetail =+ e instanceof RpcError && e.code === 'GatewayError' ? e.stringField('detail') : undefined;+ setCreateError(serverDetail ?? failureText(e, 'Could not create from this template.'));+ setPhase('failed');+ return false;+ }+ if (result.kind === 'refused') {+ const bySlot = new Map<string, string[]>();+ for (const p of result.problems)+ bySlot.set(p.slot, [...(bySlot.get(p.slot) ?? []), p.message]);+ for (const { i, setup } of pending) {+ const mine = bySlot.get(setup.name);+ setSlot(i, {+ status: mine ? 'failed' : 'idle',+ step: mine ? 'create' : null,+ error: mine ? mine.join(' ') : null,+ });+ }+ // Refused before anything existed: the room was never tried. Undone+ // after the agents were made: the room is where it failed.+ if (room) setRoomStatus(result.problems.length > 0 ? 'idle' : 'failed');+ setNothingKept(true);+ setRefusedPerAgent(result.problems.length > 0 && result.leftBehind.length === 0);+ const leftBehind =+ result.leftBehind.length > 0+ ? ` ${result.leftBehind.join(', ')} could not be deleted again; delete ${result.leftBehind.length === 1 ? 'it' : 'them'} from Your Agents.`+ : '';+ setCreateError(+ (result.problems.length > 0+ ? 'Nothing was created. Each agent says what stopped it.'+ : result.message) + leftBehind+ );+ setPhase('failed');+ return false;+ }+ for (const agent of result.createdAgents) {+ const match = pending.find(({ setup }) => setup.name === agent.slot);+ if (!match) continue;+ setSlot(match.i, {+ status: 'created',+ step: null,+ createdName: agent.name,+ createdSwitchAgentId: agent.agentId,+ });+ created.push({ slotIndex: match.i, name: agent.name, switchAgentId: agent.agentId });+ }+ const deaf = result.createdAgents.filter((a) => !a.listening).map((a) => a.name);+ if (deaf.length > 0 && result.room)+ toast({+ title: `${deaf.join(', ')} may not have seen the first message`,+ description: `${deaf.length === 1 ? 'It was' : 'They were'} still starting when the room was made. Mention ${deaf.length === 1 ? 'it' : 'them'} in the room to start work.`,+ variant: 'destructive',+ });+ if (result.room) createdRoom.current = result.room;+ return true;+ };++ /** Say how the rooms came out, and open the first. */+ const showRoomResult = (result: ProvisionFromTemplateResult) => {+ if (result.kind === 'room') {+ if (result.failedAttachments.length > 0) {+ const kickoff = result.failedAttachments.find((f) => f.kind === 'kickoff');+ const others = result.failedAttachments.filter((f) => f.kind !== 'kickoff');+ toast({+ title: kickoff+ ? `"${result.roomName}" exists, but nobody has spoken in it yet`+ : `"${result.roomName}" was created with gaps`,+ description: [+ kickoff ? `The first message could not be posted: ${kickoff.error}` : null,+ others.length > 0+ ? `Could not add: ${others.map((f) => `${f.id} (${f.error})`).join(', ')}`+ : null,+ ]+ .filter(Boolean)+ .join(' '),+ variant: 'destructive',+ });+ }+ // Open the room. The kickoff and the agents' answers appear there, and the+ // agents' sessions appear in the sidebar.+ finish(`Opening ${result.roomName}…`, () => navigate('room', { roomId: result.roomId }));+ } else {+ const gaps = [+ ...result.errors.map((e) => e.error),+ ...result.rooms.flatMap((r) =>+ r.failedAttachments.map((f) => `${r.roomName}: ${f.id} (${f.error})`)+ ),+ ];+ if (gaps.length > 0) {+ toast({+ title: `"${result.groupName}" was created with gaps`,+ description: gaps.join('; '),+ variant: 'destructive',+ });+ } else {+ toast({+ title: `"${result.groupName}" is ready`,+ description: `${result.rooms.length} room${result.rooms.length === 1 ? '' : 's'} created.`,+ });+ }+ const first = result.rooms[0];+ finish(first ? `Opening ${first.roomName}…` : 'Opening Your Rooms…', () =>+ first ? navigate('room', { roomId: first.roomId }) : navigate('serverRooms', { serverId })+ );+ }+ };++ /**+ * A version 2 template: the whole run in one request, from the document and+ * the inputs. The server works out which agents and rooms the conditions+ * make, their machines and providers, and checks it whole; nothing is kept+ * when it refuses, and each reason shows on its agent.+ */+ const createFromDocument = async () => {+ if (!loaded || workspaceId === null) return;+ const pending = slots+ .map((slot, i) => ({ slot, i, setup: setups[i]! }))+ .filter(({ setup }) => setup.on && setup.existing === null);+ const filled = Object.fromEntries(+ slots.flatMap((slot, i) =>+ setups[i]?.on && setups[i]?.existing && slot.entry.key+ ? [[slot.entry.key, setups[i]!.existing!]]+ : []+ )+ );+ const inputs: Record<string, string | number | boolean> = {};+ for (const param of templateParams) {+ const value = values[param.name];+ if (isEmpty(value)) continue;+ inputs[param.name] = param.type === 'number' ? Number(value) : (value as string | boolean);+ }+ setNothingKept(false);+ setRefusedPerAgent(false);+ for (const { i } of pending) setSlot(i, { status: 'creating', error: null, step: 'create' });+ if (makesRoom) setRoomStatus('creating');+ let result: TemplateRunResult;+ try {+ const template = loaded.instructions+ ? await rpc.agentTemplates.compose({+ yamlText: loaded.yamlText,+ instructions: loaded.instructions,+ })+ : loaded.yamlText;+ result = await rpc.workspaces.runTemplateDocument(workspaceId, {+ template,+ inputs,+ filled,+ templateName: loaded.name,+ });+ } catch (e) {+ for (const { i } of pending) setSlot(i, { status: 'failed', step: null });+ if (makesRoom) setRoomStatus('failed');+ const serverDetail =+ e instanceof RpcError && e.code === 'GatewayError' ? e.stringField('detail') : undefined;+ setCreateError(serverDetail ?? failureText(e, 'Could not create from this template.'));+ setPhase('failed');+ return;+ }+ if (result.kind === 'refused') {+ const bySlot = new Map<string, string[]>();+ for (const p of result.problems)+ bySlot.set(p.slot, [...(bySlot.get(p.slot) ?? []), p.message]);+ const unmatched = result.problems.filter(+ (p) => !pending.some(({ setup }) => setup.name === p.slot)+ );+ for (const { i, setup } of pending) {+ const mine = bySlot.get(setup.name);+ setSlot(i, {+ status: mine ? 'failed' : 'idle',+ step: mine ? 'create' : null,+ error: mine ? mine.join(' ') : null,+ });+ }+ if (makesRoom) setRoomStatus(result.problems.length > 0 ? 'idle' : 'failed');+ setNothingKept(true);+ setRefusedPerAgent(+ result.problems.length > 0 && unmatched.length === 0 && result.leftBehind.length === 0+ );+ setCreateError(+ unmatched.length > 0 || result.problems.length === 0+ ? result.message+ : 'Nothing was created. Each agent says what stopped it.'+ );+ setPhase('failed');+ return;+ }+ for (const agent of result.createdAgents) {+ const match = pending.find(({ setup }) => setup.name === agent.name);+ if (match)+ setSlot(match.i, {+ status: 'created',+ step: null,+ createdName: agent.name,+ createdSwitchAgentId: agent.agentId,+ });+ }+ await agentsStore.load().catch(() => {});+ await queryClient+ .invalidateQueries({ queryKey: workspaceAgentsQueryKey(workspaceId) })+ .catch(() => {});+ const deaf = result.createdAgents.filter((a) => !a.listening).map((a) => a.name);+ if (deaf.length > 0 && result.room)+ toast({+ title: `${deaf.join(', ')} may not have seen the first message`,+ description: 'Mention it in the room to start work.',+ variant: 'destructive',+ });+ if (result.room) {+ setRoomStatus('created');+ await refreshSidebarRoomState(true).catch(() => {});+ showRoomResult(result.room);+ return;+ }+ finish('Opening Your Agents…', () => navigate('serverAgents', { serverId }));+ };+const createAll = async () => {if (!loaded || workspaceId === null || blockedReason !== null) return;setPhase('creating');@@ -788,13 +1324,20 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {setFieldErrors({});const created: { slotIndex: number; name: string; switchAgentId: string | null }[] = [];- for (let i = 0; i < slots.length; i++) {+ if (isV2) {+ await createFromDocument();+ return;+ }+ if (management && newSlots.length > 0) {+ if (!(await createManaged(created))) return;+ }+ for (let i = 0; i < (management ? 0 : slots.length); i++) {const slot = slots[i];const setup = setups[i];- if (slot.mode !== 'new' || slot.status === 'created') continue;+ if (setup.existing !== null || slot.status === 'created') continue;const name = slot.createdName ?? setup.name;const providerId = setup.provider;- if (!providerId) continue;+ if (!providerId || setup.location === null) continue;const sshHost = setup.location === LOCAL_RUN_LOCATION ? null : setup.location;setSlot(i, { status: 'creating', error: null, step: 'prepare' });try {@@ -880,17 +1423,6 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {.invalidateQueries({ queryKey: workspaceAgentsQueryKey(workspaceId) }).catch(() => {});}- // A recent is used again from its own text, so a bundled template whose- // instructions live in a separate file is stored with them inlined.- void (async () => {- const yamlText = loaded.instructions- ? await rpc.agentTemplates.compose({- yamlText: loaded.yamlText,- instructions: loaded.instructions,- })- : loaded.yamlText;- await rpc.roomTemplates.saveRecent({ serverId, name: loaded.name, yamlText });- })().catch(() => {});// Rooms the agents join: the one this page was opened from, and the ones// the template names for each agent.@@ -901,9 +1433,10 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {// stops and says so rather than opening the room without them.const missingJoin: string[] = [];slots.forEach((slot, i) => {+ const existing = setups[i].existing;const agentId =- slot.mode === 'existing'- ? (byAgentName.get(slot.existingName) ?? null)+ existing !== null+ ? (byAgentName.get(existing) ?? null): (slot.createdSwitchAgentId ??created.find((c) => c.slotIndex === i)?.switchAgentId ??null);@@ -983,38 +1516,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {// the agents got, so the server finds them.setRoomStatus('creating');try {- const replacements: Record<string, string> = {};- slots.forEach((slot, i) => {- const expression = slot.entry.name ?? '';- const actual =- slot.mode === 'existing' ? slot.existingName : (slot.createdName ?? setups[i].name);- if (expression && actual && expression !== actual) replacements[expression] = actual;- });- let coreYaml = await rpc.agentTemplates.substituteSlots({- coreYaml: loaded.coreYaml,- replacements,- });- if (!isGroupDoc) {- // The member lists are rebuilt from the parsed template, so the renamed- // agents must be renamed here too, or the original names would come back.- const slotNamesSet = new Set(slots.map((s) => s.entry.name ?? ''));- const keep = (list: string[]) =>- list- .filter((a) => hasPlaceholder(a) || slotNamesSet.has(a))- .map((a) => replacements[a] ?? a);- coreYaml = await rpc.roomTemplates.rewriteYaml({- yamlText: coreYaml,- agents: [...new Set([...keep(parsed.agents), ...editedAgents])],- users: [...keep(parsed.users), ...editedUsers],- });- }- const inputs = serverInputs(templateParams, values, loaded.serverParamNames);- if (loaded.singular && slots.length === 1) {- // The singular `agent:` form: the server fills `{agent}` from this input.- const slot = slots[0];- inputs.agent =- slot.mode === 'existing' ? slot.existingName : (slot.createdName ?? setups[0].name);- }+ const { coreYaml, inputs } = await roomRequest(loaded.coreYaml, parsed);const result =createdRoom.current ??(await rpc.workspaces.createRoomFromTemplate(workspaceId, coreYaml, inputs, loaded.name));@@ -1022,52 +1524,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {setRoomStatus('created');// The room exists whether or not the sidebar refreshes.await refreshSidebarRoomState(true).catch(() => {});- if (result.kind === 'room') {- if (result.failedAttachments.length > 0) {- const kickoff = result.failedAttachments.find((f) => f.kind === 'kickoff');- const others = result.failedAttachments.filter((f) => f.kind !== 'kickoff');- toast({- title: kickoff- ? `"${result.roomName}" exists, but nobody has spoken in it yet`- : `"${result.roomName}" was created with gaps`,- description: [- kickoff ? `The first message could not be posted: ${kickoff.error}` : null,- others.length > 0- ? `Could not add: ${others.map((f) => `${f.id} (${f.error})`).join(', ')}`- : null,- ]- .filter(Boolean)- .join(' '),- variant: 'destructive',- });- }- // Open the room. The kickoff and the agents' answers appear there, and the- // agents' sessions appear in the sidebar.- finish(`Opening ${result.roomName}…`, () => navigate('room', { roomId: result.roomId }));- } else {- const gaps = [- ...result.errors.map((e) => e.error),- ...result.rooms.flatMap((r) =>- r.failedAttachments.map((f) => `${r.roomName}: ${f.id} (${f.error})`)- ),- ];- if (gaps.length > 0) {- toast({- title: `"${result.groupName}" was created with gaps`,- description: gaps.join('; '),- variant: 'destructive',- });- } else {- toast({- title: `"${result.groupName}" is ready`,- description: `${result.rooms.length} room${result.rooms.length === 1 ? '' : 's'} created.`,- });- }- const first = result.rooms[0];- finish(first ? `Opening ${first.roomName}…` : 'Opening Your Rooms…', () =>- first ? navigate('room', { roomId: first.roomId }) : navigate('serverRooms', { serverId })- );- }+ showRoomResult(result);} catch (e) {setRoomStatus('failed');const serverDetail =@@ -1100,21 +1557,22 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {// Values for the preview cards: the inputs, `{agent}` for a single-agent// template, and every agent's final name.const railValues: Values =- loaded?.singular && setups[0] ? { ...values, agent: setups[0].name || '{agent}' } : values;+ loaded?.singular && setups[0] ? { ...values, agent: setups[0].name || '{agent}' } : namedValues;const railRenames = useMemo(() => {const out: Record<string, string> = {};slots.forEach((slot, i) => {- const expression = slot.entry.name ?? '';- const actual =- slot.mode === 'existing' ? slot.existingName : (slot.createdName ?? setups[i]?.name);+ const expression = slot.entry.key ?? slot.entry.name ?? '';+ const actual = setups[i]?.existing ?? slot.createdName ?? setups[i]?.name;if (expression && actual && expression !== actual) out[expression] = actual;});return out;}, [slots, setups]);// ── Render ──────────────────────────────────────────────────────────────+ // A run refused whole kept nothing: the next Create is a fresh run, not a retry.const partlyDone =- slots.some((s) => s.status === 'created' || s.status === 'failed') || roomStatus === 'failed';+ !nothingKept &&+ (slots.some((s) => s.status === 'created' || s.status === 'failed') || roomStatus === 'failed');const roomCount = makesRoom ? (parsed?.rooms.length ?? 0) : 0;const primaryLabel = partlyDone? 'Retry remaining steps'@@ -1155,7 +1613,7 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {// The rows of the creating screen: one per call the run makes.const createSteps: CreateStep[] = slots.flatMap((slot, i) =>- slot.mode === 'new'+ setups[i]?.existing === null && setups[i]?.on? agentCreateSteps(i, {name: slot.createdName ?? setups[i]?.name ?? 'the agent',status: slot.status,@@ -1163,6 +1621,8 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {clones: slot.cloneRepo && !!slot.entry.repoUrl,setsPolicy: !!slot.entry.addressing,cloneWarning: slot.cloneWarning,+ managed: management ? { machine: setups[i]?.machine?.name ?? null } : null,+ error: slot.error,}): []);@@ -1200,47 +1660,73 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {}: null;- /** One param as the template says to show it: asked, folded, or fixed.- * Inside the Advanced fold an `advanced` param is a plain field: the fold does the folding. */- const paramRow = (- param: ParamSpec,- sshHost: string | null,- inFold = false,- /** The agent whose section the row sits in, for a directory param's resolved path. */- slotIndex: number | null = null- ) => {- const value = values[param.name] ?? '';- const error = fieldErrors[param.name] ?? clashErrors[param.name] ?? valueProblem(param, value);- const resolvedDirectory =- param.type === 'directory' && slotIndex !== null && setups[slotIndex]?.directory- ? setups[slotIndex].directory- : null;- const summary =- param.type === 'provider'- ? (providerDisplayName(String(value)) ?? String(value))- : param.type === 'location'- ? runLocationLabel(String(value) || LOCAL_RUN_LOCATION, allowedHosts)+ /** The SSH host of the agent a param is read by, for a control that depends on that machine. */+ const sshHostOf = (param: ParamSpec): string | null => {+ const location = setups[agentIndexOf(param)]?.location ?? null;+ return location === null || location === LOCAL_RUN_LOCATION ? null : location;+ };++ /** The directory a directory param resolves to for the agent reading it. */+ const directoryShownFor = (param: ParamSpec): string => {+ const setup = setups[agentIndexOf(param)];+ if (!setup) return '';+ return management && setup.managedDirectory+ ? shownDirectory(setup.managedDirectory, setup.machine)+ : setup.directory;+ };++ /** How a value reads on one line, folded. */+ const summaryOf = (param: ParamSpec, value: string | number | boolean): string => {+ const resolvedDirectory = param.type === 'directory' ? directoryShownFor(param) : '';+ return param.type === 'provider'+ ? (providerDisplayName(String(value)) ?? String(value))+ : param.type === 'location' && !management+ ? value === ''+ ? ''+ : runLocationLabel(String(value), allowedHosts)+ : param.type === 'machine' || param.type === 'location'+ ? (() => {+ const m = machines?.find((c) => c.id === value || c.name === value);+ return m ? machineLabel(m) : String(value);+ })(): param.type === 'room' && value === NEW? (newRoomForPick?.name ?? 'New room'): param.type === 'directory'- ? (resolvedDirectory ?? String(value)).replace(/^\/(?:Users|home)\/[^/]+/, '~')+ ? (resolvedDirectory || String(value)).replace(/^\/(?:Users|home)\/[^/]+/, '~'): String(value);+ };++ /** One param as the template says to show it: asked, folded, or fixed.+ * Inside the Advanced fold an `advanced` param is a plain field: the fold does the folding. */+ const paramRow = (param: ParamSpec, inFold = false) => {+ const value = values[param.name] ?? '';+ const error = fieldErrors[param.name] ?? clashErrors[param.name] ?? valueProblem(param, value);+ const summary = summaryOf(param, value);if (param.input === 'fixed') {return <FixedRow key={param.name} label={paramLabel(param)} value={summary} />;}// A directory param's value can read `{$agents_dir}` and `{agent}`; the// control shows the path they resolve to, and an edit writes a literal.- const shown = resolvedDirectory ?? value;+ // A managed agent's keeps `{$agents_dir}`, the machine's own folder, so an+ // edit still writes something the server can resolve.+ const resolvedDirectory =+ param.type === 'directory'+ ? management+ ? setups[agentIndexOf(param)]?.managedDirectory || null+ : setups[agentIndexOf(param)]?.directory || null+ : null;const field = (<ParamFieldkey={param.name}param={param}- value={shown}+ value={resolvedDirectory ?? value}onChange={(v) => setValues((prev) => ({ ...prev, [param.name]: v }))}error={error}lists={lists}- sshHost={sshHost}+ sshHost={sshHostOf(param)}hosts={allowedHosts}+ machines={machines}+ locationAsMachine={management}newRoom={newRoomForPick}disabled={busy}onNavigateAway={() =>@@ -1268,133 +1754,6 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {return field;};- /** A summary line for the fold: each folded value, in order. */- const foldSummary = (rows: ParamSpec[], directory: string, asksDirectory: boolean) =>- [- ...rows.map((p) => {- const v = values[p.name] ?? '';- return p.type === 'provider'- ? (providerDisplayName(String(v)) ?? String(v))- : p.type === 'location'- ? runLocationLabel(String(v) || LOCAL_RUN_LOCATION, allowedHosts)- : p.type === 'directory'- ? (directory || String(v)).replace(/^\/(?:Users|home)\/[^/]+/, '~')- : String(v);- }),- ...(asksDirectory ? [directory.replace(/^\/(?:Users|home)\/[^/]+/, '~')] : []),- ]- .filter((v) => v !== '')- .join(' · ');-- /** The section for one agent entry: what it asks, then one fold with what the template settled. */- const agentSection = (slot: AgentSlot, i: number) => {- const setup = setups[i];- const sshHost = setup.location === LOCAL_RUN_LOCATION ? null : setup.location;- const own = paramsOfAgent(i);- const shared = i === 0 ? [providerParam, locationParam, directoryParam] : [];- const rows = [...own, ...shared.filter((p): p is ParamSpec => p !== null && !own.includes(p))];- const asked = rows.filter((p) => p.input === 'ask');- const folded = rows.filter((p) => p.input !== 'ask');- const asksProvider = !slot.entry.provider && !providerParam && slot.mode === 'new';- const asksDirectory = !slot.entry.directory && !directoryParam && slot.mode === 'new';- const isRemote = sshHost !== null;- const foldKey = `fold:${i}`;- const foldSettled =- folded.every(- (p) =>- p.input === 'fixed' ||- (!isEmpty(values[p.name]) &&- (fieldErrors[p.name] ?? valueProblem(p, values[p.name] ?? '')) === null)- ) &&- (!asksDirectory || (setup.directory !== '' && !slot.dirPicked)) &&- hostReachable &&- hostReady;- const hasFold = folded.length > 0 || asksDirectory;- const foldLabel = loaded?.form.advanced.label ?? 'Advanced';- return (- <div key={i} className="flex flex-col gap-4">- {slots.length > 1 && (- <SectionTitle- title={setup.name && !hasPlaceholder(setup.name) ? setup.name : `Agent ${i + 1}`}- hint={slot.entry.description || undefined}- />- )}- {asked.map((p) => paramRow(p, sshHost, false, i))}- {asksProvider && (- <div className="flex flex-col gap-2">- <div className="flex items-baseline gap-2">- <span className="text-[12.5px] font-medium">Provider</span>- <span className="flex-1" />- <span className="text-[11px] text-amber-600 dark:text-amber-400">Required</span>- </div>- <p className="text-xs text-foreground-muted">- The template names no coding agent. Only what{' '}- {runLocationLabel(setup.location, allowedHosts)} has installed is offered.- </p>- {hostReachable ? (- <AgentTypePicker- value={pickedProvider}- onChange={setPickedProvider}- sshHost={sshHost ?? undefined}- onNavigateAway={() => navigate('settings', { tab: 'clis-models' })}- />- ) : (- <p className="text-xs text-foreground-passive">Waiting for the host…</p>- )}- </div>- )}- {hasFold && (- <CollapsibleInput- label={foldLabel}- summary={foldSummary(folded, setup.directory, asksDirectory)}- collapsed={- phase === 'form' &&- !(loaded?.form.advanced.open ?? false) &&- !opened.has(foldKey) &&- foldSettled- }- onOpen={() => open(foldKey)}- disabled={busy}- wrap- >- <div className="flex flex-col gap-5 rounded-[10px] border border-border px-4 py-4">- <span className="text-[12.5px] font-medium">{foldLabel}</span>- {folded.map((p) => paramRow(p, sshHost, true, i))}- {asksDirectory && (- <div className="flex flex-col gap-2">- <span className="text-[12.5px] font-medium">Directory</span>- <p className="text-xs text-foreground-muted">- The template names no directory, so the agent gets a folder of its own under the- one this Console keeps agents in.- </p>- <SlotDirectoryField- slot={{ ...slot, dir: setup.directory }}- onChange={(next) =>- setSlots((prev) => prev.map((x, j) => (j === i ? next : x)))- }- sshHost={sshHost}- busy={busy}- />- </div>- )}- {isRemote && <HostReachabilityNotice sshHost={setup.location} />}- {isRemote &&- hostReachable &&- firstRemote === setup.location &&- !hostReadiness.checking && (- <HostReadinessNotice- sshHost={setup.location}- readiness={hostReadiness}- onNavigateAway={() => navigate('remoteHosts')}- />- )}- </div>- </CollapsibleInput>- )}- </div>- );- };-const memberLists = (<>{showAgentLists && (@@ -1425,22 +1784,14 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {</>);- const otherRoomParams = roomParams.filter((p) => p !== joinParam);- const roomDetails = (- <>- {otherRoomParams.filter((p) => p.input !== 'advanced').map((p) => paramRow(p, null))}- {makesRoom && memberLists}- {otherRoomParams.filter((p) => p.input === 'advanced').map((p) => paramRow(p, null))}- </>- );const roomSummary =joinValue === NEW? `New room: ${newRoomForPick?.name ?? 'from the template'}`: joinValue || 'Pick a room';- const roomSection = joinParam ? (- // The template leaves the room to the deployer: one switch, and the- // details only once it is on. Off, the agent is created on its own.- <div className="flex flex-col gap-4">+ // The template leaves the room to the deployer: one switch, and the room+ // choice under it only once it is on. Off, the agents are created on their own.+ const joinSwitch = joinParam ? (+ <div key={joinParam.name} className="flex flex-col gap-4"><label className="flex cursor-pointer items-start gap-3"><Switchchecked={roomOn}@@ -1454,9 +1805,9 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {className="mt-0.5"/><span className="flex flex-col gap-0.5">- <span className="text-sm font-semibold text-foreground">{paramLabel(joinParam)}</span>+ <span className="text-[12.5px] font-medium text-foreground">{paramLabel(joinParam)}</span>{joinParam.description && (- <span className="text-[12.5px] leading-relaxed text-foreground-muted">+ <span className="text-xs leading-relaxed text-foreground-muted">{joinParam.description}</span>)}@@ -1489,26 +1840,72 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {{null}</CollapsibleInput>)}- {roomDetails}</div>)}</div>- ) : hasRoomPart || roomParams.length > 0 || intoRoomId ? (- <div className="flex flex-col gap-4">- <SectionTitle- title={roomCount > 1 ? 'Rooms' : 'Room'}- hint={- intoRoomId- ? `The agent joins ${intoRoomName ?? 'the room'} you came from.`- : roomParams.length === 0 && makesRoom- ? 'Created as the template describes, with the agent in it.'- : undefined- }- />- {roomDetails}- </div>) : null;+ // The inputs, in the order the template declares them. A param only the+ // room reads is left out while the room is not being made, since it does+ // nothing then. `advanced` and `fixed` params sit together in the+ // template's fold, below the asked ones, in the same order.+ const shownParams = templateParams.filter(+ (p) => p === joinParam || makesRoom || !roomOnly.has(p.name)+ );+ const askedRows = shownParams.filter((p) => p === joinParam || p.input === 'ask');+ const foldedRows = shownParams.filter((p) => p !== joinParam && p.input !== 'ask');+ const foldLabel = loaded?.form.advanced.label ?? 'Advanced';+ const foldSettled = foldedRows.every(+ (p) =>+ p.input === 'fixed' ||+ (!isEmpty(values[p.name]) &&+ (fieldErrors[p.name] ?? valueProblem(p, values[p.name] ?? '')) === null)+ );+ const fold =+ foldedRows.length > 0 ? (+ <CollapsibleInput+ label={foldLabel}+ summary={foldedRows+ .map((p) => summaryOf(p, values[p.name] ?? ''))+ .filter((v) => v !== '')+ .join(' · ')}+ collapsed={+ phase === 'form' &&+ !(loaded?.form.advanced.open ?? false) &&+ !opened.has('fold') &&+ foldSettled+ }+ onOpen={() => open('fold')}+ disabled={busy}+ wrap+ >+ <div className="flex flex-col gap-5 rounded-[10px] border border-border px-4 py-4">+ <span className="text-[12.5px] font-medium">{foldLabel}</span>+ {foldedRows.map((p) => paramRow(p, true))}+ </div>+ </CollapsibleInput>+ ) : null;++ /** The notices about the machine a new agent runs on, for its card. */+ const hostNotices = (setup: SlotSetup) => {+ const sshHost =+ setup.location === null || setup.location === LOCAL_RUN_LOCATION ? null : setup.location;+ if (management) return null;+ if (sshHost === null) return null;+ return (+ <>+ <HostReachabilityNotice sshHost={sshHost} />+ {hostReachable && firstRemote === sshHost && !hostReadiness.checking && (+ <HostReadinessNotice+ sshHost={sshHost}+ readiness={hostReadiness}+ onNavigateAway={() => navigate('remoteHosts')}+ />+ )}+ </>+ );+ };+return (<div className="relative z-10 flex min-h-0 flex-1 flex-col overflow-hidden bg-background"><div className="flex shrink-0 items-start gap-4 border-b border-border px-8 pt-8 pb-5 [-webkit-app-region:drag]">@@ -1570,9 +1967,9 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {templateName={loaded.name}phase={phase}steps={createSteps}- error={runError ?? null}+ error={refusedPerAgent ? null : (runError ?? null)}doneDetail={doneDetail}- onRetry={() => void createAll()}+ onRetry={nothingKept ? null : () => void createAll()}onBack={() => setPhase('form')}/>)}@@ -1635,24 +2032,12 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {</Alert>)}- {createsAgents && (- <>- <SectionTitle- title={slots.length === 1 ? 'Agent' : 'Agents'}- hint={- templateParams.length === 0- ? 'This template asks for nothing. Create it as it is, or open Advanced.'- : undefined- }- />- {slots.map(agentSection)}- </>- )}- {createsAgents && roomSection && <div className="border-t border-border" />}- {!createsAgents && templateParams.length === 0 && (+ {templateParams.length === 0 && (<p className="text-sm text-foreground-muted">This template asks for nothing.</p>)}- {roomSection}+ {askedRows.map((p) => (p === joinParam ? joinSwitch : paramRow(p)))}+ {makesRoom && memberLists}+ {fold}</div>{/* Right: what this will create */}@@ -1664,35 +2049,70 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {</span><span className="text-[13px] font-semibold">What this will create</span></span>- <span- className={cn(- 'shrink-0 text-[11.5px]',- missing.length > 0 || slotProblems.length > 0 || invalid.length > 0- ? 'text-amber-600 dark:text-amber-400'- : 'text-emerald-700 dark:text-emerald-400'- )}- >- {stillNeeded}- </span></div><div className="flex min-h-0 flex-1 flex-col gap-4 overflow-auto px-5 py-4"><div className="flex flex-col gap-2">- {slots.map((slot, i) => (- <AgentSlotCard- key={i}- slot={slot}- wantedName={setups[i]?.name ?? ''}- onChange={(next) =>- setSlots((prev) => prev.map((s, j) => (j === i ? next : s)))- }- lists={lists}- locationLabel={runLocationLabel(- setups[i]?.location ?? LOCAL_RUN_LOCATION,- allowedHosts- )}- choice={loaded.kind === 'group'}- />- ))}+ {slots.map((slot, i) => {+ const setup = setups[i];+ if (!setup || !setup.on) return null;+ return (+ <AgentSlotCard+ key={i}+ slot={slot}+ wantedName={setup.name}+ runtime={+ setup.existing !== null+ ? null+ : management+ ? {+ provider: setup.provider+ ? (providerDisplayName(setup.provider) ?? setup.provider)+ : null,+ location: setup.machine+ ? setup.machine.state === 'online'+ ? machineLabel(setup.machine)+ : `${machineLabel(setup.machine)} (${setup.machine.state})`+ : (setup.machineText ?? null),+ directory:+ setup.managedDirectory === ''+ ? null+ : shownDirectory(setup.managedDirectory, setup.machine),+ model: slot.entry.model+ ? interpolate(slot.entry.model, values)+ : null,+ connections: connectionStates(+ setup.connections,+ connectionsQuery.data ?? null+ ),+ managed: true,+ }+ : {+ provider: setup.provider+ ? (providerDisplayName(setup.provider) ?? setup.provider)+ : null,+ location:+ setup.location === null+ ? null+ : runLocationLabel(setup.location, allowedHosts),+ directory:+ setup.directory === ''+ ? null+ : setup.directory.replace(/^\/(?:Users|home)\/[^/]+/, '~'),+ model: null,+ connections: [],+ managed: false,+ }+ }+ onChange={(next) =>+ setSlots((prev) => prev.map((s, j) => (j === i ? next : s)))+ }+ lists={lists}+ busy={busy}+ >+ {hostNotices(setup)}+ </AgentSlotCard>+ );+ })}{intoRoomId ? (<p className="px-1 text-xs text-foreground-muted">Joins{' '}@@ -1711,13 +2131,13 @@ const TemplateUsePanel = observer(function TemplateUsePanel() {</p>))}{makesRoom &&- parsed?.rooms.map((room, i) => (+ (isV2 ? roomsOn : (parsed?.rooms ?? [])).map((room, i) => (<RoomCardkey={i}room={room}values={railValues}renames={railRenames}- bridgeName={templateBridge?.displayName ?? parsed.bridge}+ bridgeName={templateBridge?.displayName ?? parsed?.bridge ?? null}creatorIdentity={creatorIdentity}status={roomStatus}toggle={null}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/templates-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/templates-view.tsxindex 8193fc4fb..34b4c8f54 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/templates-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/templates-view.tsx@@ -2,20 +2,16 @@ import {Bot,Boxes,CircleAlert,- Clock,DoorOpen,FileText,Loader2,- Save,+ MoreVertical,+ Trash2,Upload,UserRound,- Users,} from 'lucide-react';import { observer } from 'mobx-react-lite';import { useCallback, useEffect, useMemo, useState } from 'react';-import type { TemplateKind } from '@main/core/agent-templates/template-document';-import type { TemplateSummary } from '@main/core/agent-templates/template-summary';-import type { RecentTemplate } from '@main/core/room-templates/controller';import type { StoredTemplateSummary } from '@main/core/switch-servers/gateway-client';import type { GuardResult, ViewDefinition } from '@renderer/app/view-registry';import { ServerPage } from '@renderer/features/switch-servers/server-page';@@ -31,14 +27,15 @@ import { useAgentTypeAvailability } from '@renderer/lib/stores/use-agent-type-avimport { Alert, AlertAction, AlertDescription } from '@renderer/lib/ui/alert';import { Badge } from '@renderer/lib/ui/badge';import { Button } from '@renderer/lib/ui/button';+import {+ DropdownMenu,+ DropdownMenuContent,+ DropdownMenuItem,+ DropdownMenuTrigger,+} from '@renderer/lib/ui/dropdown-menu';import { SearchInput } from '@renderer/lib/ui/search-input';import { SegmentedControl } from '@renderer/lib/ui/segmented-control';import { Toggle } from '@renderer/lib/ui/toggle';-import { cn } from '@renderer/utils/utils';-import { prefillForSave } from './agent-template-data';-import { bundledTemplates } from './bundled-templates';-import { formatTimeAgo, runMatches } from './template-runs';-import { RECENT_ACTION, RECENT_ROW, TemplateRunRow, useTemplateRuns } from './template-runs-list';function useServerId(): string {return useParams('templates').params.serverId;@@ -68,17 +65,13 @@ const KIND_ICON: Record<Kind, typeof Bot> = {group: Boxes,};-/** One card in the listing: a bundled template, or a template saved on the workspace. */+/** One card in the listing: a template on the workspace, official or saved by someone. */type TemplateListEntry = {- /** The id the card opens: a bundled id, or a workspace template id. */id: string;kind: Kind;name: string;description: string;- bundled: boolean;- server: StoredTemplateSummary | null;- /** The document text, when it is available without a request (a bundled template). */- content: string | null;+ server: StoredTemplateSummary;};function kindOf(kind: string): Kind {@@ -98,71 +91,6 @@ function hasFiles(e: React.DragEvent): boolean {return Array.from(e.dataTransfer.types).includes('Files');}-function plural(n: number, noun: string): string {- return `${n} ${noun}${n === 1 ? '' : 's'}`;-}--/** The card's summary line, for example "Creates 1 room and 2 agents · 4 inputs".- * An agent template's room is optional, so its card names the agent alone. */-function summaryLine(s: TemplateSummary): string {- const parts: string[] = [];- if (s.rooms > 0 && s.kind !== 'agent') parts.push(plural(s.rooms, 'room'));- if (s.agents > 0) parts.push(s.kind === 'agent' ? 'an agent' : plural(s.agents, 'agent'));- const creates = parts.length > 0 ? `Creates ${parts.join(' and ')}` : 'Creates nothing yet';- const inputs = s.inputs === 0 ? 'nothing to fill in' : plural(s.inputs, 'input');- return `${creates} · ${inputs}`;-}--// The listing endpoint returns no document text, and the summary line-// needs the document. Each card fetches its own once per version of the-// template and keeps it for the session.-const summaryCache = new Map<string, Promise<TemplateSummary>>();--function fetchSummary(workspaceId: string, item: TemplateListEntry): Promise<TemplateSummary> {- // The version is part of the key, so an edit made elsewhere refreshes the- // card as soon as the listing reports it.- const key = `${workspaceId}:${item.id}:${item.server?.version ?? 0}`;- let pending = summaryCache.get(key);- if (!pending) {- pending = (async () => {- const yamlText =- item.content ??- (- await rpc.workspaces.getTemplateDetail({- workspaceId,- templateId: item.id,- })- ).definition;- return rpc.agentTemplates.summarize({ yamlText });- })();- pending.catch(() => summaryCache.delete(key));- summaryCache.set(key, pending);- }- return pending;-}--function useTemplateSummary(- workspaceId: string | null,- item: TemplateListEntry-): TemplateSummary | null {- const [summary, setSummary] = useState<TemplateSummary | null>(null);- useEffect(() => {- if (workspaceId === null) return;- let cancelled = false;- fetchSummary(workspaceId, item)- .then((s) => {- if (!cancelled) setSummary(s);- })- .catch(() => {- // The card renders without the summary line when the document cannot be fetched.- });- return () => {- cancelled = true;- };- }, [workspaceId, item]);- return summary;-}-function OwnerRow({ name, mine }: { name: string; mine: boolean }) {const initial = (name.trim()[0] ?? '?').toUpperCase();return (@@ -179,23 +107,24 @@ function OwnerRow({ name, mine }: { name: string; mine: boolean }) {}function TemplateCard({- workspaceId,item,meId,busy,onOpen,onUse,+ onDelete,}: {- workspaceId: string | null;item: TemplateListEntry;meId: string | null;busy: boolean;onOpen: () => void;onUse: () => void;+ /** Null when the signed-in user may not delete it. */+ onDelete: (() => void) | null;}) {const Icon = KIND_ICON[item.kind];- const summary = useTemplateSummary(workspaceId, item);- const mine = item.server !== null && meId !== null && item.server.ownerId === meId;+ const official = item.server.official;+ const mine = !official && meId !== null && item.server.ownerId === meId;return (<div className="group relative flex min-h-[168px] flex-col rounded-[11px] border border-border bg-background transition-colors hover:border-border-1"><button@@ -205,32 +134,47 @@ function TemplateCard({onClick={onOpen}/><div className="pointer-events-none flex flex-1 flex-col gap-2 p-4">- <div className="flex items-center gap-2">+ <div className={`flex items-center gap-2${onDelete ? ' pr-7' : ''}`}><Icon className="size-4.5 shrink-0 text-foreground-muted" /><h3 className="min-w-0 truncate font-medium text-foreground">{item.name}</h3>- {item.bundled && (- <Badge variant="outline" title="Shipped with Switch">+ {official && (+ <Badge variant="outline" title="Comes with Switch">Official</Badge>)}- {item.server && mine && !item.bundled && <Badge variant="secondary">Yours</Badge>}- {item.bundled && item.server && (- <Badge variant="secondary" title="A copy is saved on this workspace; it lists below">- <Users />- Saved- </Badge>- )}+ {mine && <Badge variant="secondary">Yours</Badge>}</div><p className="line-clamp-3 text-sm text-foreground-muted">{item.description || <span className="italic">No description.</span>}</p><div className="mt-auto flex flex-col gap-1.5 pt-1 pr-16">- <span className="text-xs text-foreground-passive">- {summary ? summaryLine(summary) : ' '}- </span>- {item.server && !item.bundled && <OwnerRow name={item.server.creator} mine={mine} />}+ {!official && <OwnerRow name={item.server.creator} mine={mine} />}</div></div>+ {onDelete && (+ <div className="absolute top-2.5 right-2.5">+ <DropdownMenu>+ <DropdownMenuTrigger+ render={+ <Button+ variant="ghost"+ size="sm"+ className="size-7 p-0"+ aria-label={`${item.name} actions`}+ >+ <MoreVertical className="size-4" />+ </Button>+ }+ />+ <DropdownMenuContent align="end">+ <DropdownMenuItem variant="destructive" onClick={onDelete}>+ <Trash2 className="size-4" />+ Delete template…+ </DropdownMenuItem>+ </DropdownMenuContent>+ </DropdownMenu>+ </div>+ )}{/* On top of the overlay: the one action that does not need the page. */}<div className="absolute right-3 bottom-3"><Button size="sm" variant="outline" onClick={onUse} disabled={busy}>@@ -241,191 +185,9 @@ function TemplateCard({);}-function Section({- title,- subtitle,- children,-}: {- title: string;- subtitle: string;- children: React.ReactNode;-}) {- return (- <section>- <h3 className="text-sm font-semibold text-foreground">{title}</h3>- <p className="mt-0.5 mb-3 text-xs text-foreground-muted">{subtitle}</p>- {children}- </section>- );-}--/**- * What was used lately: the template runs the server records for this- * workspace, newest first, then the documents used from this Console, kept- * locally per workspace. A run opens to show the rooms it made; a document can- * be used again or saved to the workspace, where everyone can find it.- */-function RecentsSection({- serverId,- workspaceId,- serverName,- onWorkspace,- kind,- query,- onSaved,-}: {- serverId: string;- workspaceId: string | null;- serverName: string | null;- /** Names of templates saved on the workspace. A recent with one of these names gets no Save button. */- onWorkspace: ReadonlySet<string>;- /** The listing's kind filter and search text. They apply to the recents too. Only mine does not: every recent is the user's own. */- kind: KindFilter;- query: string;- onSaved: () => void;-}) {- const { navigate } = useNavigate();- const showSaveModal = useShowModal('saveTemplateModal');- // Each recent with its kind, classified by the same parser as the listing.- const [recents, setRecents] = useState<(RecentTemplate & { kind: TemplateKind })[] | null>(null);- const [saving, setSaving] = useState<string | null>(null);- const { runs, replace: replaceRun } = useTemplateRuns(workspaceId);-- useEffect(() => {- let cancelled = false;- void (async () => {- try {- const list = await rpc.roomTemplates.getRecents(serverId);- // One row per name. The same template used before and after an edit is two- // documents with one name, and only the newest use is offered.- const newest = list.filter((r, i) => list.findIndex((o) => o.name === r.name) === i);- const classified = await Promise.all(- newest.map(async (r) => ({- ...r,- kind: await rpc.agentTemplates- .kind({ yamlText: r.yamlText })- .catch(() => 'room' as const),- }))- );- if (!cancelled) setRecents(classified);- } catch {- if (!cancelled) setRecents([]);- }- })();- return () => {- cancelled = true;- };- }, [serverId]);-- const saveToWorkspace = async (recent: RecentTemplate) => {- setSaving(recent.yamlText);- try {- const prefill = await prefillForSave(recent.yamlText, recent.name);- showSaveModal({- serverId,- serverName,- content: recent.yamlText,- ...prefill,- onSuccess: onSaved,- });- } catch (error) {- toast({- title: `Could not read "${recent.name}"`,- description: failureText(error, 'The document did not parse.'),- variant: 'destructive',- });- } finally {- setSaving(null);- }- };-- const needle = query.trim().toLowerCase();- const shown = (recents ?? []).filter(- (r) =>- (kind === 'all' || r.kind === kind) &&- (needle.length === 0 || r.name.toLowerCase().includes(needle))- );- // A run creates rooms, so an agents-only listing leaves them out.- const shownRuns = kind === 'agent' ? [] : runs.filter((r) => runMatches(r, needle));- if (shown.length === 0 && shownRuns.length === 0) return null;-- return (- <section>- <h3 className="flex items-center gap-1.5 text-sm font-semibold text-foreground">- <Clock className="size-3.5 text-foreground-muted" />- Recently used- </h3>- <p className="mt-0.5 mb-3 text-xs text-foreground-muted">- Template runs on this workspace, and documents you used from this Console. Documents are- kept here only; Save to workspace makes one a template everyone on the workspace can find.- </p>- <div className="divide-y divide-border rounded-md border border-border">- <div className={cn(RECENT_ROW, 'text-[11px] font-medium text-foreground-passive')}>- <span>Name</span>- <span>Status</span>- <span>Size</span>- <span>When</span>- <span />- </div>- {workspaceId !== null &&- shownRuns.map((run) => (- <TemplateRunRow- key={run.rootRoomId}- workspaceId={workspaceId}- run={run}- onChanged={replaceRun}- />- ))}- {shown.map((r) => {- const Icon = KIND_ICON[r.kind];- const saved = onWorkspace.has(r.name);- return (- <div key={r.yamlText} className={RECENT_ROW}>- <button- type="button"- onClick={() =>- navigate('templateImport', {- serverId,- yamlText: r.yamlText,- sourceName: r.name,- })- }- className="flex min-w-0 cursor-pointer items-center gap-2 text-left hover:underline"- >- <Icon className="size-3.5 shrink-0 text-foreground-muted" />- <span className="truncate">{r.name}</span>- </button>- <span className="text-xs text-foreground-passive">{saved ? 'Saved' : ''}</span>- <span />- <span className="text-xs text-foreground-passive">{formatTimeAgo(r.usedAt)}</span>- <span className="flex justify-end">- {!saved && (- <Button- type="button"- variant="outline"- size="sm"- className={RECENT_ACTION}- title="Save to the workspace, so everyone on it can use it"- disabled={saving === r.yamlText}- onClick={() => void saveToWorkspace(r)}- >- <Save className="size-3.5" />- Save to workspace- </Button>- )}- </span>- </div>- );- })}- </div>- </section>- );-}-const TemplatesPanel = observer(function TemplatesPanel() {const serverId = useServerId();const workspaceId = workspacesStore.idOnServerInScope(serverId);- const server = switchServersStore.servers.find((s) => s.id === serverId);const meId = switchServersStore.statusFor(serverId)?.user?.id ?? null;const { navigate } = useNavigate();@@ -442,9 +204,8 @@ const TemplatesPanel = observer(function TemplatesPanel() {const [dragging, setDragging] = useState(0);const [reloadKey, setReloadKey] = useState(0);const reload = useCallback(() => setReloadKey((k) => k + 1), []);- // The server searches name and description. The full listing stays loaded- // for the recents and for marking a built-in as saved; the search results- // replace it only for the workspace cards.+ // The server searches name and description; its hits replace the listing+ // while there is a search.const [searchHits, setSearchHits] = useState<StoredTemplateSummary[] | null>(null);useEffect(() => {const q = query.trim();@@ -478,8 +239,8 @@ const TemplatesPanel = observer(function TemplatesPanel() {const noProvider = availability !== undefined && !availability.some((a) => a.available);useEffect(() => {- // No workspace is an answer, not a wait. The bundled templates below still- // render; leaving the spinner up would claim a list is on its way.+ // No workspace is an answer, not a wait: leaving the spinner up would+ // claim a list is on its way.if (workspaceId === null) {setTemplates([]);setListError('This server has no workspace yet, so its templates cannot be read.');@@ -495,8 +256,7 @@ const TemplatesPanel = observer(function TemplatesPanel() {if (!cancelled) setTemplates(result);}).catch((e: unknown) => {- // The bundled templates render either way. A failed request is shown as a- // failure, not as an empty workspace.+ // A failed request is shown as a failure, not as an empty workspace.if (!cancelled) {setTemplates([]);setListError(failureText(e, 'Could not read this workspace’s templates.'));@@ -510,31 +270,13 @@ const TemplatesPanel = observer(function TemplatesPanel() {};}, [workspaceId, reloadKey]);- const { builtIn, onWorkspace } = useMemo(() => {- // A bundled card is always the bundled document. Saving it creates a- // workspace template, listed below as the user's own; the bundled card- // only marks that a copy exists. Names are unique per owner, so only the- // user's own template of that name counts as the copy.- const byName = new Map(- templates.filter((t) => meId !== null && t.ownerId === meId).map((t) => [t.name, t])- );- const builtIn: TemplateListEntry[] = bundledTemplates.map((b) => ({- id: b.id,- kind: kindOf(b.kind),- name: b.name,- description: b.description,- bundled: true,- server: byName.get(b.name) ?? null,- content: b.yamlText,- }));+ const templatesShown = useMemo(() => {const onWorkspace: TemplateListEntry[] = (searchHits ?? templates).map((t) => ({id: t.id,kind: kindOf(t.kind),name: t.name,description: t.description,- bundled: false,server: t,- content: null,}));const needle = query.trim().toLowerCase();const matches = (t: TemplateListEntry) =>@@ -542,14 +284,43 @@ const TemplatesPanel = observer(function TemplatesPanel() {(needle.length === 0 ||t.name.toLowerCase().includes(needle) ||t.description.toLowerCase().includes(needle) ||- (t.server?.creator ?? '').toLowerCase().includes(needle));- const mine = (t: TemplateListEntry) => meId !== null && t.server?.ownerId === meId;- return {- builtIn: onlyMine ? [] : builtIn.filter(matches),- onWorkspace: onWorkspace.filter((t) => matches(t) && (!onlyMine || mine(t))),- };+ t.server.creator.toLowerCase().includes(needle));+ const mine = (t: TemplateListEntry) => meId !== null && t.server.ownerId === meId;+ // One list: the badges on each card (Official, Yours, who saved it) say+ // where it comes from.+ return onWorkspace.filter((t) => matches(t) && (!onlyMine || mine(t)));}, [templates, searchHits, query, kind, onlyMine, meId]);+ const confirm = useShowModal('confirmActionModal');+ const me = switchServersStore.statusFor(serverId)?.user ?? null;+ // The server says who may delete; an older server leaves it out, and the owner-or-admin guess stands in.+ const canDelete = (item: TemplateListEntry) =>+ !item.server.official &&+ (item.server.canManage ??+ ((meId !== null && item.server.ownerId === meId) || me?.role === 'admin'));+ const deleteTemplate = (item: TemplateListEntry) =>+ confirm({+ title: `Delete ${item.name}?`,+ description: 'It is removed from this workspace for everyone. This cannot be undone.',+ confirmLabel: 'Delete',+ onSuccess: () => {+ if (workspaceId === null) return;+ rpc.workspaces+ .deleteTemplate({ workspaceId, templateId: item.id })+ .then(() => {+ toast({ title: `"${item.name}" deleted` });+ reload();+ })+ .catch((e: unknown) =>+ toast({+ title: `Could not delete "${item.name}"`,+ description: failureText(e, 'Check the server connection and try again.'),+ variant: 'destructive',+ })+ );+ },+ });+const handleUse = (item: TemplateListEntry) =>navigate('templateUse', { serverId, templateId: item.id });@@ -573,12 +344,12 @@ const TemplatesPanel = observer(function TemplatesPanel() {const card = (item: TemplateListEntry) => (<TemplateCardkey={item.id}- workspaceId={workspaceId}item={item}meId={meId}busy={false}onOpen={() => open(item)}onUse={() => handleUse(item)}+ onDelete={canDelete(item) ? () => deleteTemplate(item) : null}/>);@@ -586,7 +357,7 @@ const TemplatesPanel = observer(function TemplatesPanel() {<ServerPagewidth={1000}title="Templates"- description="A template is one YAML document that creates a room, an agent, or a group of them. Use one, fill in its inputs, and everything it describes appears on this workspace."+ description="Templates create agents and rooms on this workspace. Pick one, fill in what it asks, and everything it describes is created in one go, or nothing is."action={<Button size="sm" onClick={() => navigate('templateImport', { serverId })}><Upload className="size-4" />@@ -678,65 +449,36 @@ const TemplatesPanel = observer(function TemplatesPanel() {</Toggle></div>- {!onlyMine && (- <Section- title="Built in"- subtitle="Shipped with Switch. Use one to see how a template is put together."- >- {builtIn.length > 0 ? (- <div className={grid}>{builtIn.map(card)}</div>- ) : (- <p className="text-sm text-foreground-muted">No built-in template matches.</p>- )}- </Section>- )}-- <Section- title="On this workspace"- subtitle="Saved here. Each one says who can use it and who can change it."- >- {onWorkspace.length > 0 ? (- <div className={grid}>{onWorkspace.map(card)}</div>- ) : listError ? (- <div className="flex flex-col items-start gap-2 rounded-[11px] border border-border px-4 py-4">- <p className="text-sm text-foreground-muted">{listError}</p>- <Button size="sm" variant="outline" onClick={reload}>- Try again- </Button>- </div>- ) : filtering ? (+ {templatesShown.length > 0 ? (+ <div className={grid}>{templatesShown.map(card)}</div>+ ) : listError ? (+ <div className="flex flex-col items-start gap-2 rounded-[11px] border border-border px-4 py-4">+ <p className="text-sm text-foreground-muted">{listError}</p>+ <Button size="sm" variant="outline" onClick={reload}>+ Try again+ </Button>+ </div>+ ) : filtering ? (+ <p className="text-sm text-foreground-muted">+ {onlyMine+ ? 'None of yours match. Import a template and it shows up here as yours.'+ : 'No template matches.'}+ </p>+ ) : (+ <div className="flex flex-col items-start gap-3 rounded-[11px] border border-dashed border-border px-4 py-5"><p className="text-sm text-foreground-muted">- {onlyMine- ? 'None of yours match. Save a template you used, or import one, and it shows up here as yours.'- : 'No template on this workspace matches.'}+ No template here yet. Import one, and everyone on this workspace finds it here.</p>- ) : (- <div className="flex flex-col items-start gap-3 rounded-[11px] border border-dashed border-border px-4 py-5">- <p className="text-sm text-foreground-muted">- Nothing saved here yet. Import a template, or save one you have used, and- everyone on this workspace finds it here.- </p>- <Button- size="sm"- variant="outline"- onClick={() => navigate('templateImport', { serverId })}- >- <Upload className="size-3.5" />- Import a template- </Button>- </div>- )}- </Section>-- <RecentsSection- serverId={serverId}- workspaceId={workspaceId}- serverName={server?.name ?? null}- onWorkspace={new Set(templates.map((t) => t.name))}- kind={kind}- query={query}- onSaved={reload}- />+ <Button+ size="sm"+ variant="outline"+ onClick={() => navigate('templateImport', { serverId })}+ >+ <Upload className="size-3.5" />+ Import a template+ </Button>+ </div>+ )}</div>)}</div>diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/creates-rail.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/use/creates-rail.tsxindex e738868bd..45727eb4f 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/creates-rail.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/creates-rail.tsx@@ -2,33 +2,28 @@ import { Check, ChevronRight, DoorOpen, Loader2, TriangleAlert } from 'lucide-reimport { useState } from 'react';import type { ParsedAgentEntry } from '@main/core/agent-templates/template-document';import type { TemplateRoom } from '@main/core/room-templates/controller';-import { LocalDirectorySelector } from '@renderer/features/locations/components/add-agent-modal/local-directory-selector';import { AgentField, type EntityLists } from '@renderer/features/room-templates/entity-fields';import { workspacesStore } from '@renderer/features/workspaces/workspaces-store';import { AgentAvatar } from '@renderer/lib/components/agent-avatar';-import { Input } from '@renderer/lib/ui/input';import { SegmentedControl } from '@renderer/lib/ui/segmented-control';import { Switch } from '@renderer/lib/ui/switch';import { cn } from '@renderer/utils/utils';+import type { ConnectionState } from './managed-run';import { hasPlaceholder, interpolate, type Values } from './use-template-model';export type SlotStatus = 'idle' | 'creating' | 'created' | 'failed';/*** One agent entry of the template and the choices made for it on the Use- * page: create it or use an existing agent, its working directory, whether- * to clone its repository, and its creation status.+ * page: create it or, when the template allows it, use an existing agent;+ * whether to clone its repository; and how far creation got.*/export type AgentSlot = {entry: ParsedAgentEntry;-+ /** `existing` only for an entry whose template sets `allow_existing: true`. */mode: 'new' | 'existing';/** The existing agent's name, when `mode` is `existing`. */existingName: string;- /** The working directory for a new agent: a local path, or a path on the host. */- dir: string;- /** Whether the deployer chose the directory; a chosen path stays put when the name changes. */- dirPicked: boolean;cloneRepo: boolean;status: SlotStatus;error: string | null;@@ -49,8 +44,6 @@ export function newSlot(entry: ParsedAgentEntry): AgentSlot {entry,mode: 'new',existingName: '',- dir: '',- dirPicked: false,cloneRepo: true,status: 'idle',error: null,@@ -156,77 +149,59 @@ export function RoomCard({);}-/** Where a new agent works: its directory, and whether the template's repository is cloned into it. */-export function SlotDirectoryField({- slot,- onChange,- sshHost,- busy,-}: {- slot: AgentSlot;- onChange: (next: AgentSlot) => void;- sshHost: string | null;- busy: boolean;-}) {+/** What runs a new agent, where, and in which folder, as the inputs resolve them. */+export type SlotRuntime = {+ provider: string | null;+ location: string | null;+ directory: string | null;+ /** The model, when the template names one. */+ model: string | null;+ /** The deployer's connections it is granted, and whether each is ready to grant. */+ connections: ConnectionState[];+ /** A managed agent on one of the deployer's machines, rather than one this Console runs. */+ managed: boolean;+};++function RuntimeRow({ label, value }: { label: string; value: string | null }) {return (- <>- <div className="flex flex-col gap-1">- <span className="text-[11px] text-foreground-passive">Directory</span>- {sshHost ? (- <Input- value={slot.dir}- disabled={busy}- placeholder="/home/agent/repo"- className="font-mono text-xs"- onChange={(e) => onChange({ ...slot, dir: e.target.value, dirPicked: true })}- />- ) : (- <LocalDirectorySelector- title="Choose the agent's working directory"- message="The agent runs from here. A suggested folder is created when the agent is."- path={slot.dir}- onPathChange={(dir) => onChange({ ...slot, dir, dirPicked: true })}- />+ <div className="flex items-baseline gap-3 text-xs">+ <span className="w-[72px] shrink-0 text-foreground-passive">{label}</span>+ <span+ className={cn(+ 'min-w-0 flex-1 truncate font-mono',+ value === null ? 'text-amber-600 dark:text-amber-400' : 'text-foreground-muted')}- </div>- {slot.entry.repoUrl && (- <label className="flex w-max cursor-pointer items-center gap-2 text-xs text-foreground-muted">- <Switch- size="sm"- checked={slot.cloneRepo}- onCheckedChange={(cloneRepo) => onChange({ ...slot, cloneRepo })}- />- Clone {slot.entry.repoUrl.replace(/^https?:\/\//, '')} into it- </label>- )}- </>+ >+ {value ?? 'Not set by the template'}+ </span>+ </div>);}export function AgentSlotCard({slot,wantedName,+ runtime,onChange,lists,- locationLabel,- choice = true,+ busy,+ children,}: {slot: AgentSlot;/** The name the agent is created under, as far as the inputs resolve it. */wantedName: string;+ /** What a new agent runs with. Null for an existing agent. */+ runtime: SlotRuntime | null;onChange: (next: AgentSlot) => void;lists: EntityLists;- /** The run location's display name, shown under the existing-agent picker. */- locationLabel: string;- /** Whether the deployer may point the slot at an existing agent. An agent- * template always makes a new one, so its card offers no choice. */- choice?: boolean;+ busy: boolean;+ /** Notices about the machine it runs on. */+ children?: React.ReactNode;}) {+ const existing = slot.mode === 'existing';+ const existingName = slot.existingName;const unresolved = hasPlaceholder(wantedName) || wantedName === '';- const shownName =- slot.mode === 'existing'- ? slot.existingName || 'Pick an agent'- : (slot.createdName ?? wantedName);+ const shownName = existing ? existingName || 'Pick an agent' : (slot.createdName ?? wantedName);const serverId =lists.workspaceId === null ? null : workspacesStore.serverIdFor(lists.workspaceId);return (@@ -237,7 +212,9 @@ export function AgentSlotCard({<divclassName={cn('truncate font-mono text-[13px] font-medium',- unresolved && slot.mode === 'new' ? 'text-foreground-passive' : 'text-foreground'+ (existing ? existingName === '' : unresolved)+ ? 'text-foreground-passive'+ : 'text-foreground')}>{shownName || 'Named by an input'}@@ -246,14 +223,16 @@ export function AgentSlotCard({{slot.entry.description || 'An agent with its own instructions'}</div></div>- <span className="shrink-0 text-[11px] text-foreground-passive">Agent</span>+ <span className="shrink-0 text-[11px] text-foreground-passive">+ {existing ? 'Existing agent' : 'Agent'}+ </span></div>- {/* An agent that exists can no longer change how it is made, even when a- later step for it failed. */}- {(slot.status === 'idle' || slot.status === 'failed') &&- slot.createdName === null &&- choice && (+ {/* Offered only when the template allows it. An agent that exists can no+ longer change how it is made, even when a later step for it failed. */}+ {slot.entry.allowExisting &&+ (slot.status === 'idle' || slot.status === 'failed') &&+ slot.createdName === null && (<div className="mt-3 flex flex-col gap-2.5 border-t border-border pt-3"><SegmentedControlvalue={slot.mode}@@ -265,22 +244,61 @@ export function AgentSlotCard({ariaLabel={`How to fill ${wantedName || 'this agent'}`}className="w-max"/>- {slot.mode === 'existing' ? (- <div className="flex flex-col gap-1.5">- <AgentField- value={slot.existingName}- onChange={(name) => onChange({ ...slot, existingName: name })}- lists={lists}- />- <p className="text-[11px] text-foreground-passive">- {lists.agents.length === 0- ? `No agent of yours runs on ${locationLabel} yet.`- : `Agents of yours that run on ${locationLabel}.`}- </p>- </div>- ) : null}+ {existing && (+ <AgentField+ value={slot.existingName}+ onChange={(name) => onChange({ ...slot, existingName: name })}+ lists={lists}+ />+ )}</div>)}++ {runtime && (+ <div className="mt-3 flex flex-col gap-1.5 border-t border-border pt-3">+ <RuntimeRow label="Provider" value={runtime.provider} />+ <RuntimeRow label={runtime.managed ? 'Machine' : 'Runs on'} value={runtime.location} />+ <RuntimeRow label="Directory" value={runtime.directory} />+ {runtime.model && <RuntimeRow label="Model" value={runtime.model} />}+ {runtime.connections.length > 0 && (+ <div className="flex items-baseline gap-3 text-xs">+ <span className="w-[72px] shrink-0 text-foreground-passive">Connections</span>+ <ul className="flex min-w-0 flex-1 flex-col gap-1">+ {runtime.connections.map((c) => (+ <li key={c.service} className="flex min-w-0 flex-col">+ <span className="flex items-center gap-1.5">+ {c.ready ? (+ <Check className="size-3 text-emerald-700 dark:text-emerald-400" />+ ) : (+ <TriangleAlert className="size-3 text-amber-600 dark:text-amber-400" />+ )}+ <span className="text-foreground-muted">{c.name}</span>+ {c.repos.length > 0 && (+ <span className="truncate font-mono text-foreground-passive">+ {c.repos.join(', ')}+ </span>+ )}+ </span>+ {c.note && <span className="text-amber-600 dark:text-amber-400">{c.note}</span>}+ </li>+ ))}+ </ul>+ </div>+ )}+ {!runtime.managed && slot.entry.repoUrl && slot.createdName === null && (+ <label className="mt-1 flex w-max cursor-pointer items-center gap-2 text-xs text-foreground-muted">+ <Switch+ size="sm"+ checked={slot.cloneRepo}+ disabled={busy}+ onCheckedChange={(cloneRepo) => onChange({ ...slot, cloneRepo })}+ />+ Clone {slot.entry.repoUrl.replace(/^https?:\/\//, '')} into it+ </label>+ )}+ {children}+ </div>+ )}{slot.status !== 'idle' && (<div className="mt-2 flex flex-col gap-1"><StatusLine slot={slot} />diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/creating-screen.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/use/creating-screen.tsxindex 9a7ad558e..66270dfc8 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/creating-screen.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/creating-screen.tsx@@ -43,7 +43,8 @@ export function CreatingScreen({error: string | null;/** Where the page goes next, shown under the finished heading. */doneDetail: string | null;- onRetry: () => void;+ /** Null when the run kept nothing, so there is nothing to retry from: back to the form instead. */+ onRetry: (() => void) | null;onBack: () => void;}) {const done = steps.filter((s) => s.status === 'done').length;@@ -65,16 +66,20 @@ export function CreatingScreen({{phase === 'done'? `${templateName} is ready`: phase === 'failed'- ? 'Stopped at one step'+ ? onRetry+ ? 'Stopped at one step'+ : 'Nothing was created': `Creating ${templateName}`}</h3><p className="text-[13px] text-foreground-muted">{phase === 'done'? (doneDetail ?? 'Opening it…'): phase === 'failed'- ? done > 0- ? 'What was created stays created.'- : 'Nothing was created.'+ ? !onRetry+ ? 'The run was refused as a whole. Change what each step says, then create again.'+ : done > 0+ ? 'What was created stays created.'+ : 'Nothing was created.': 'This takes a few seconds.'}</p></div>@@ -111,6 +116,7 @@ export function CreatingScreen({{STATUS_WORD[step.status]}</span></div>+ {step.error && <p className="pl-7 text-[11.5px] text-destructive">{step.error}</p>}{step.warning && (<p className="pl-7 text-[11.5px] text-amber-700 dark:text-amber-400">{step.warning}@@ -124,10 +130,12 @@ export function CreatingScreen({<div className="flex flex-col gap-3">{error && <p className="text-[13px] text-destructive">{error}</p>}<div className="flex items-center justify-center gap-2">- <Button size="sm" onClick={onRetry}>- Retry remaining steps- </Button>- <Button size="sm" variant="outline" onClick={onBack}>+ {onRetry && (+ <Button size="sm" onClick={onRetry}>+ Retry remaining steps+ </Button>+ )}+ <Button size="sm" variant={onRetry ? 'outline' : 'default'} onClick={onBack}>Back to the form</Button></div>diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.test.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.test.tsnew file mode 100644index 000000000..9f02400d9--- /dev/null+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.test.ts@@ -0,0 +1,187 @@+import { describe, expect, it } from 'vitest';+import type { ParsedAgentEntry } from '@main/core/agent-templates/template-document';+import type { OwnedMachine } from '@shared/core/managed-agents/managed-agents';+import type { ConnectionCatalogEntry } from '@shared/core/switch-servers/connection-catalog';+import {+ connectionStates,+ connectionsFor,+ directoryUnresolved,+ machineFor,+ machineProblem,+ managedDirectory,+ runAgent,+ shownDirectory,+} from './managed-run';++function machine(overrides: Partial<OwnedMachine>): OwnedMachine {+ return {+ id: 'm1',+ name: 'laptop',+ kind: 'console',+ state: 'online',+ providers: [{ provider: 'claude', ready: true, problem: null }],+ acceptsLogins: true,+ cloud: false,+ workspacesDir: '/home/me/.switch/agents',+ os: 'linux',+ local: { kind: 'this-computer' },+ ...overrides,+ };+}++function entry(overrides: Partial<ParsedAgentEntry>): ParsedAgentEntry {+ return {+ name: 'a',+ displayName: null,+ description: '',+ instructions: 'Do it.',+ repoUrl: null,+ sources: [],+ addressing: null,+ provider: 'claude',+ location: null,+ machine: null,+ model: null,+ advancedConfig: {},+ isolation: null,+ autoApprove: null,+ connections: [],+ directory: null,+ join: [],+ placeholders: [],+ allowExisting: false,+ key: null,+ condition: null,+ ...overrides,+ };+}++const LAPTOP = machine({});+const BOX = machine({+ id: 'm2',+ name: 'box',+ state: 'offline',+ local: { kind: 'ssh-host', sshHost: 'box.lan' },+});++describe('machineFor', () => {+ it('finds a machine by id or by name', () => {+ expect(machineFor([LAPTOP, BOX], 'm2', null, false)).toBe(BOX);+ expect(machineFor([LAPTOP, BOX], 'laptop', null, false)).toBe(LAPTOP);+ });++ it('puts a location that is no machine on the first online one that can run it', () => {+ const coder = machine({+ id: 'm4',+ name: 'cluster',+ providers: [{ provider: 'codex', ready: true, problem: null }],+ });+ // "local" or an SSH host is this Console's idea: the server's $first stands in.+ expect(machineFor([BOX, coder, LAPTOP], 'local', 'claude', true)).toBe(LAPTOP);+ expect(machineFor([BOX, coder, LAPTOP], 'dev-vm', 'codex', true)).toBe(coder);+ expect(machineFor([BOX], 'local', 'claude', true)).toBeNull();+ });++ it('does not replace a machine the template names', () => {+ expect(machineFor([LAPTOP], 'nowhere', 'claude', false)).toBeNull();+ expect(machineFor([LAPTOP, machine({ id: 'm3' })], 'laptop', null, false)).toBeNull();+ });+});++describe('machineProblem', () => {+ it('says when the machine cannot take the agent', () => {+ expect(machineProblem(BOX, 'claude', 'a')).toMatch(/box is offline/);+ expect(machineProblem(LAPTOP, 'codex', 'a')).toBe('codex is not installed on laptop.');+ expect(+ machineProblem(+ machine({ providers: [{ provider: 'claude', ready: false, problem: 'not logged in' }] }),+ 'claude',+ 'a'+ )+ ).toBe('claude on laptop is not ready: not logged in.');+ expect(machineProblem(LAPTOP, 'claude', 'a')).toBeNull();+ });+});++describe('connectionsFor', () => {+ it('grants what the template lists, and nothing for a repo', () => {+ expect(+ connectionsFor(+ entry({+ repoUrl: 'https://github.com/acme/widgets.git',+ connections: [{ service: 'github', access: 'write', repos: ['acme/{repo}'] }],+ }),+ { repo: 'tools' }+ )+ ).toEqual([{ service: 'github', access: 'write', repos: ['acme/tools'] }]);+ expect(connectionsFor(entry({ repoUrl: 'https://github.com/acme/widgets' }), {})).toEqual([]);+ });+});++describe('connectionStates', () => {+ const catalog = [+ { slug: 'github', name: 'GitHub', status: 'connected', unavailable_reason: null },+ { slug: 'atlassian', name: 'Atlassian', status: 'not_connected', unavailable_reason: null },+ ] as ConnectionCatalogEntry[];++ it('says whether the deployer can grant each connection', () => {+ const states = connectionStates(+ [+ { service: 'github', access: null, repos: ['acme/widgets'] },+ { service: 'atlassian', access: null, repos: [] },+ { service: 'nope', access: null, repos: [] },+ ],+ catalog+ );+ expect(states.map((s) => [s.name, s.ready, s.note])).toEqual([+ ['GitHub', true, null],+ ['Atlassian', false, 'Connect Atlassian under Connections first.'],+ ['nope', false, 'This server has no such connection.'],+ ]);+ });+});++describe('directories', () => {+ it('keeps {$agents_dir} for the server and fills the rest', () => {+ const directory = managedDirectory('{$agents_dir}/{team}/{agent}', { team: 'red' }, 'a');+ expect(directory).toBe('{$agents_dir}/red/a');+ expect(directoryUnresolved(directory)).toBe(false);+ expect(directoryUnresolved(managedDirectory('{root}/a', {}, 'a'))).toBe(true);+ expect(shownDirectory(directory, LAPTOP)).toBe('/home/me/.switch/agents/red/a');+ });+});++describe('runAgent', () => {+ it('sends the agent as the server takes it', () => {+ const agent = runAgent({+ slot: 'red-a',+ name: 'red-a',+ entry: entry({+ description: 'Works on {team}',+ model: '{model}',+ advancedConfig: { effort: '{effort}' },+ isolation: 'isolated',+ autoApprove: '{yolo}',+ addressing: 'owner-agents',+ repoUrl: 'https://github.com/acme/widgets',+ }),+ values: { team: 'red', model: 'sonnet', effort: 'high', yolo: true },+ displayName: null,+ provider: 'claude',+ machine: LAPTOP,+ directoryText: '{$agents_dir}/red-a',+ });+ expect(agent).toMatchObject({+ description: 'Works on red',+ machine: 'm1',+ model: 'sonnet',+ advancedConfig: { effort: 'high' },+ isolation: 'isolated',+ autoApprove: true,+ directory: null,+ addressing: 'owner-agents',+ connections: [],+ });+ expect(agent.instructions).toContain('clone https://github.com/acme/widgets into it');+ });+});diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.tsnew file mode 100644index 000000000..de1f976a9--- /dev/null+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/managed-run.ts@@ -0,0 +1,208 @@+import type {+ ParsedAgentEntry,+ TemplateConnection,+} from '@main/core/agent-templates/template-document';+import type { TemplateRunAgent } from '@main/core/switch-servers/gateway-client';+import type { OwnedMachine } from '@shared/core/managed-agents/managed-agents';+import type { ConnectionCatalogEntry } from '@shared/core/switch-servers/connection-catalog';+import { hasPlaceholder, interpolate, type Values } from './use-template-model';++/**+ * A template run on a server with agent management: every agent the+ * template creates is a managed agent on one of the deployer's machines, and+ * the whole run (agents, then rooms) goes to the server in one request,+ * which checks it whole and keeps nothing when it fails.+ */++const AGENTS_DIR = '{$agents_dir}';++/**+ * The texts of an entry's runtime fields, for telling whether a param is read+ * by one. The renderer's copy of the main process's: the renderer can import+ * only types from `@main`.+ */+export function runtimeFieldTexts(+ agent: Pick<ParsedAgentEntry, 'provider' | 'location' | 'machine' | 'directory'>+): string[] {+ return [agent.provider ?? '', agent.location ?? '', agent.machine ?? '', agent.directory ?? ''];+}++/**+ * The machine a new agent runs on, among the deployer's machines on the+ * server. `machineText` names one by id or name, from the template's+ * `machine` (or, on a server with agent management, its `location`). A+ * `location` this Console knows (this computer, an SSH host) means nothing to+ * the server, so when it names no machine the first online machine that can+ * run the provider stands in, as `$first`. An explicit `machine` that names+ * none is not replaced: null.+ */+export function machineFor(+ machines: readonly OwnedMachine[],+ machineText: string | null,+ provider: string | null,+ fallBackToFirst: boolean+): OwnedMachine | null {+ if (machineText !== null && machineText !== '') {+ const byId = machines.find((m) => m.id === machineText);+ if (byId) return byId;+ const named = machines.filter((m) => m.name === machineText);+ if (named.length === 1) return named[0]!;+ if (!fallBackToFirst) return null;+ }+ return fallBackToFirst ? firstReady(machines, provider) : null;+}++/** `$first` among the deployer's machines: the first online one, by name, that can run `provider`. */+export function firstReady(+ machines: readonly OwnedMachine[],+ provider: string | null+): OwnedMachine | null {+ return (+ [...machines]+ .sort((a, b) => a.name.localeCompare(b.name))+ .find(+ (m) =>+ m.state === 'online' &&+ (provider === null || m.providers.some((p) => p.provider === provider && p.ready))+ ) ?? null+ );+}++/** Why the machine cannot take an agent of `provider` now, or null when it can. */+export function machineProblem(+ machine: OwnedMachine,+ provider: string | null,+ agentName: string+): string | null {+ if (machine.state !== 'online')+ return `${machine.name} is ${machine.state}. Start its controller, or run ${agentName} elsewhere.`;+ if (provider === null) return null;+ const entry = machine.providers.find((p) => p.provider === provider);+ if (!entry) return `${provider} is not installed on ${machine.name}.`;+ if (!entry.ready)+ return `${provider} on ${machine.name} is not ready${entry.problem ? `: ${entry.problem}` : ''}.`;+ return null;+}++/**+ * The connections an entry grants, as its `connections:` lists them. A+ * `repo` grants nothing: the agent clones it itself, with a connection the+ * template lists or the machine's own credentials.+ */+export function connectionsFor(entry: ParsedAgentEntry, values: Values): TemplateConnection[] {+ return entry.connections.map((c) => ({+ service: interpolate(c.service, values),+ access: c.access,+ repos: c.repos.map((r) => interpolate(r, values)),+ }));+}++/** How a connection the template grants stands for the deployer. */+export type ConnectionState = {+ service: string;+ /** The service's name, or its slug when the server does not list it. */+ name: string;+ repos: string[];+ /** Connected and grantable; otherwise why not. */+ ready: boolean;+ note: string | null;+};++export function connectionStates(+ wanted: readonly TemplateConnection[],+ catalog: readonly ConnectionCatalogEntry[] | null+): ConnectionState[] {+ return wanted.map((c) => {+ const entry = catalog?.find((e) => e.slug === c.service) ?? null;+ const base = { service: c.service, name: entry?.name ?? c.service, repos: c.repos };+ if (catalog === null) return { ...base, ready: false, note: 'Checking your connections…' };+ if (entry === null)+ return { ...base, ready: false, note: 'This server has no such connection.' };+ if (entry.unavailable_reason) return { ...base, ready: false, note: entry.unavailable_reason };+ if (entry.status !== 'connected')+ return {+ ...base,+ ready: false,+ note:+ entry.status === 'needs_reauthorization'+ ? `Reconnect ${entry.name} under Connections.`+ : `Connect ${entry.name} under Connections first.`,+ };+ return { ...base, ready: true, note: null };+ });+}++/** What the server is sent for one new agent. `directory` keeps `{$agents_dir}`, which the server reads as the machine's own folder for agents. */+export function runAgent(params: {+ slot: string;+ name: string;+ entry: ParsedAgentEntry;+ values: Values;+ displayName: string | null;+ provider: string;+ machine: OwnedMachine;+ directoryText: string;+}): TemplateRunAgent {+ const { entry, values, name } = params;+ const filled = (text: string) => interpolate(text, { ...values, agent: name });+ const isolation = entry.isolation ? filled(entry.isolation) : 'shared';+ const autoApprove =+ typeof entry.autoApprove === 'string'+ ? values[entry.autoApprove.replace(/^\{|\}$/g, '')] === true+ : entry.autoApprove === true;+ const repo = entry.repoUrl ? interpolate(entry.repoUrl, values) : null;+ const instructions = repo+ ? `${entry.instructions}\n\nYou work on the repository ${repo}. If your working directory is not a clone of it yet, clone ${repo} into it first.`+ : entry.instructions;+ const directory = params.directoryText.trim();+ return {+ slot: params.slot,+ name,+ description: filled(entry.description) || name,+ displayName: params.displayName,+ instructions,+ provider: params.provider,+ machine: params.machine.id,+ model: entry.model && filled(entry.model) !== '' ? filled(entry.model) : null,+ advancedConfig: fillDeep(entry.advancedConfig, { ...values, agent: name }) as Record<+ string,+ unknown+ >,+ isolation: isolation === 'isolated' ? 'isolated' : 'shared',+ autoApprove,+ directory: directory === `${AGENTS_DIR}/${name}` ? null : directory,+ addressing: entry.addressing ?? 'owner',+ connections: connectionsFor(entry, values),+ };+}++/** The directory text for a managed agent: its field or param with the inputs and `{agent}` filled in, `{$agents_dir}` kept for the server. */+export function managedDirectory(directoryText: string, values: Values, name: string): string {+ const keep = { ...values, agent: name, $agents_dir: AGENTS_DIR };+ return interpolate(interpolate(directoryText, keep), keep);+}++/** Whether the directory is still waiting on an input: a placeholder other than `{$agents_dir}`. */+export function directoryUnresolved(directory: string): boolean {+ return hasPlaceholder(directory.split(AGENTS_DIR).join(''));+}++/** The directory as the deployer reads it, `{$agents_dir}` shown as the machine's folder when it has said where that is. */+export function shownDirectory(directory: string, machine: OwnedMachine | null): string {+ if (!directory.includes(AGENTS_DIR)) return directory;+ return machine?.workspacesDir+ ? directory.split(AGENTS_DIR).join(machine.workspacesDir.replace(/[/\\]+$/, ''))+ : directory.split(AGENTS_DIR).join(`${machine?.name ?? 'its machine'}'s agents folder`);+}++function fillDeep(node: unknown, values: Values): unknown {+ if (typeof node === 'string') {+ const whole = /^\{(\$?\w+)\}$/.exec(node);+ if (whole && values[whole[1]] !== undefined) return values[whole[1]];+ return interpolate(node, values);+ }+ if (Array.isArray(node)) return node.map((item) => fillDeep(item, values));+ if (node !== null && typeof node === 'object')+ return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, fillDeep(v, values)]));+ return node;+}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/param-field.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/use/param-field.tsxindex 54ce2b36f..5132baa9a 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/param-field.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/param-field.tsx@@ -11,9 +11,10 @@ import { Input } from '@renderer/lib/ui/input';import { Switch } from '@renderer/lib/ui/switch';import { Textarea } from '@renderer/lib/ui/textarea';import { cn } from '@renderer/utils/utils';+import type { OwnedMachine } from '@shared/core/managed-agents/managed-agents';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';import { RoomChoiceField } from './room-pick-field';-import { RunLocationSelect } from './run-location-select';+import { MachineSelect, RunLocationSelect } from './run-location-select';import { isChain, isRequired, paramLabel, typeLabel } from './use-template-model';/** One input of a template on the Use page, with the control its type calls for. */@@ -25,6 +26,8 @@ export function ParamField({lists,sshHost,hosts,+ machines,+ locationAsMachine,newRoom,disabled,onNavigateAway,@@ -38,6 +41,10 @@ export function ParamField({sshHost: string | null;/** The SSH hosts a `location` param may name. */hosts: readonly { sshHost: string; name: string }[];+ /** The owner's machines a `machine` param may name; null without agent management. */+ machines: readonly OwnedMachine[] | null;+ /** On a server with agent management, a `location` is one of the deployer's machines there. */+ locationAsMachine: boolean;/** For a `room` param: the room the template creates, offered as `$new`. */newRoom: { name: string; bridgeType: string | null } | null;disabled?: boolean;@@ -68,6 +75,10 @@ export function ParamField({onNavigateAway={onNavigateAway}/>);+ } else if (param.type === 'location' && locationAsMachine) {+ control = (+ <MachineSelect value={strVal} onChange={onChange} machines={machines} disabled={disabled} />+ );} else if (param.type === 'location') {control = (<RunLocationSelect@@ -77,23 +88,29 @@ export function ParamField({disabled={disabled}/>);- } else if (param.type === 'directory') {- control = sshHost ? (- <Input- value={strVal}- disabled={disabled}- placeholder="/home/agent/repo"- className="font-mono text-xs"- onChange={(e) => onChange(e.target.value)}- />- ) : (- <LocalDirectorySelector- title="Choose the agent's working directory"- message="The agent runs from here. The folder is created when the agent is."- path={strVal}- onPathChange={onChange}- />+ } else if (param.type === 'machine') {+ control = (+ <MachineSelect value={strVal} onChange={onChange} machines={machines} disabled={disabled} />);+ } else if (param.type === 'directory') {+ // A managed agent's directory is on its machine, not here: no folder picker.+ control =+ sshHost || locationAsMachine ? (+ <Input+ value={strVal}+ disabled={disabled}+ placeholder="/home/agent/repo"+ className="font-mono text-xs"+ onChange={(e) => onChange(e.target.value)}+ />+ ) : (+ <LocalDirectorySelector+ title="Choose the agent's working directory"+ message="The agent runs from here. The folder is created when the agent is."+ path={strVal}+ onPathChange={onChange}+ />+ );} else if (param.type === 'room') {control = (<RoomChoiceFielddiff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/run-location-select.tsx b/console/apps/switch-console-desktop/src/renderer/features/templates/use/run-location-select.tsxindex 0a6c0d0fe..ad2633653 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/run-location-select.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/run-location-select.tsx@@ -1,6 +1,12 @@import { useQuery } from '@tanstack/react-query';-import { Monitor, Server } from 'lucide-react';+import { Cloud, Monitor, Server } from 'lucide-react';import { useMemo } from 'react';+import {+ machineIdOf,+ machineLabel,+ machineRunLocation,+ machineRunLocations,+} from '@renderer/features/locations/components/add-agent-modal/server-run-locations';import { switchServersStore } from '@renderer/features/switch-servers/switch-servers-store';import { rpc } from '@renderer/lib/ipc';import {@@ -10,6 +16,7 @@ import {SelectTrigger,SelectValue,} from '@renderer/lib/ui/select';+import type { OwnedMachine } from '@shared/core/managed-agents/managed-agents';export const LOCAL_RUN_LOCATION = 'local';@@ -88,3 +95,72 @@ export function RunLocationSelect({</Select>);}++/**+ * The value a `machine` param holds for one of the owner's machines: its id.+ * Listed as the New agent modal lists them: this computer first, as "This+ * computer"; offline machines shown but not pickable; the Switch cloud machine+ * only while it is online.+ */+export function MachineSelect({+ value,+ onChange,+ machines,+ disabled,+}: {+ value: string;+ onChange: (value: string) => void;+ /** The owner's machines on the server; null when it does not run agent management. */+ machines: readonly OwnedMachine[] | null;+ disabled?: boolean;+}) {+ if (machines === null) {+ return (+ <p className="text-xs text-foreground-muted">+ This server does not run agent management, so there is no machine to choose.+ </p>+ );+ }+ const options = machineRunLocations([...machines]);+ const chosen = machines.find((m) => m.id === value || m.name === value) ?? null;+ const Icon = ({ kind }: { kind: 'monitor' | 'server' | 'cloud' }) =>+ kind === 'monitor' ? (+ <Monitor className="size-4 text-foreground-muted" />+ ) : kind === 'cloud' ? (+ <Cloud className="size-4 text-foreground-muted" />+ ) : (+ <Server className="size-4 text-foreground-muted" />+ );+ const selected = chosen+ ? options.find((o) => o.value === machineRunLocation(chosen.id))+ : undefined;+ return (+ <Select+ value={chosen ? machineRunLocation(chosen.id) : ''}+ onValueChange={(v) => onChange(v ? (machineIdOf(v) ?? '') : '')}+ disabled={disabled}+ >+ <SelectTrigger className="w-full" aria-label="Machine">+ <SelectValue>+ <Icon kind={selected?.icon ?? 'server'} />+ <span className="truncate">+ {selected+ ? selected.label+ : chosen+ ? machineLabel(chosen)+ : value || 'Choose a machine'}+ </span>+ </SelectValue>+ </SelectTrigger>+ <SelectContent>+ {options.map((o) => (+ <SelectItem key={o.value} value={o.value} disabled={o.disabled}>+ <Icon kind={o.icon} />+ <span className="flex-1 truncate">{o.label}</span>+ <span className="text-xs text-foreground-muted">{o.tag}</span>+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ );+}diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.test.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.test.tsindex fe969851b..c65ed6663 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.test.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.test.ts@@ -3,9 +3,11 @@ import type { ParamSpec } from '@main/core/room-templates/controller';import {agentCreateSteps,bridgeCandidates,+ unsaidMessage,paramLabel,+ holds,resolveChain,- sectionOf,+ roomOnlyParams,serverInputs,valueProblem,} from './use-template-model';@@ -24,6 +26,7 @@ function param(overrides: Partial<ParamSpec>): ParamSpec {pattern: null,min: null,max: null,+ condition: null,...overrides,};}@@ -93,25 +96,26 @@ describe('serverInputs', () => {});});-describe('sectionOf', () => {- const agents = [['{name}', '{provider}'], ['{other}']];- const room = 'name: "Ask {agent}"\nbridge: "{bridge}"\n';- it('puts a param with the agent that reads it, and the rest with the room', () => {- expect(sectionOf(param({ name: 'provider' }), agents, room)).toEqual({- section: 'agent',- index: 0,- });- expect(sectionOf(param({ name: 'other' }), agents, room)).toEqual({- section: 'agent',- index: 1,- });- expect(sectionOf(param({ name: 'bridge' }), agents, room)).toEqual({ section: 'room' });+describe('roomOnlyParams', () => {+ const room = 'name: "Ask {agent}"\nbridge: "{bridge}"\nusers: ["{repo}"]\n';+ it('keeps the params the room reads and no agent entry does', () => {+ const agents = [{ placeholders: ['name'] }];+ const params = [param({ name: 'name' }), param({ name: 'bridge' }), param({ name: 'repo' })];+ expect([...roomOnlyParams(params, agents, room)]).toEqual(['bridge', 'repo']);});- it('keeps a room param with the room even when an agent joins it', () => {- expect(sectionOf(param({ name: 'where', type: 'room' }), [['{where}']], room)).toEqual({- section: 'room',- });+ it("reads an agent entry whole, so a param used only in its instructions is the agent's too", () => {+ const agents = [{ placeholders: ['repo'] }, { placeholders: [] }];+ const params = [param({ name: 'bridge' }), param({ name: 'repo' })];+ expect([...roomOnlyParams(params, agents, room)]).toEqual(['bridge']);+ });+});++describe('unsaidMessage', () => {+ it('names the agent and the setting the template leaves out', () => {+ expect(unsaidMessage({ index: 0, label: '{team}-fixer', field: 'provider' })).toBe(+ 'The template never says which coding agent runs {team}-fixer. Give it a `provider:` or declare a `provider` param.'+ );});});@@ -126,7 +130,14 @@ describe('paramLabel', () => {});describe('agentCreateSteps', () => {- const base = { name: 'a', clones: false, setsPolicy: true, cloneWarning: null } as const;+ const base = {+ name: 'a',+ clones: false,+ setsPolicy: true,+ cloneWarning: null,+ managed: null,+ error: null,+ } as const;it('marks the rows before the call in progress done, the one at it running', () => {const steps = agentCreateSteps(0, { ...base, status: 'creating', step: 'create' });@@ -143,9 +154,39 @@ describe('agentCreateSteps', () => {expect(steps.map((s) => s.status)).toEqual(['done', 'done', 'failed']);});+ it('shows a managed agent as one call, with the reason it was refused', () => {+ const steps = agentCreateSteps(0, {+ ...base,+ managed: { machine: 'laptop' },+ status: 'failed',+ step: 'create',+ error: "an agent named 'a' already exists",+ });+ expect(steps).toEqual([+ {+ key: '0:create',+ label: 'Create a on laptop',+ status: 'failed',+ error: "an agent named 'a' already exists",+ },+ ]);+ });+it('has no policy row when the template sets no addressing', () => {expect(agentCreateSteps(0, { ...base, setsPolicy: false, status: 'idle', step: null })).toHaveLength(2);});});++describe('holds', () => {+ it('reads a param, or compares it', () => {+ expect(holds(null, {})).toBe(true);+ expect(holds('{on}', { on: true })).toBe(true);+ expect(holds('{on}', { on: false })).toBe(false);+ expect(holds('{start} == new_room', { start: 'new_room' })).toBe(true);+ expect(holds('{start} != new_room', { start: 'nowhere' })).toBe(true);+ expect(holds('{start} == new_room', {})).toBe(false);+ expect(holds('not a condition', {})).toBe(false);+ });+});diff --git a/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.ts b/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.tsindex 1e683a86c..24b787983 100644--- a/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/templates/use/use-template-model.ts@@ -1,3 +1,4 @@+import type { ParsedAgentEntry, UnsaidRuntime } from '@main/core/agent-templates/template-document';import type { ParamSpec } from '@main/core/room-templates/controller';import {FIRST,@@ -11,14 +12,31 @@ export type Values = Record<string, string | number | boolean>;/** Fill `{param}` and `{$builtin}` placeholders from `values`. A placeholder with no value yet is left as written. */export function interpolate(template: string, values: Values): string {- return template.replace(/\{(\$?\w+)\}/g, (match, key: string) => {+ return template.replace(/\{(\$?[\w.]+)\}/g, (match, key: string) => {const val = values[key];return val !== undefined && val !== '' ? String(val) : match;});}export function hasPlaceholder(text: string): boolean {- return /\{\$?\w+\}/.test(text);+ return /\{\$?[\w.]+\}/.test(text);+}++/**+ * Whether a version 2 condition holds with these values: `"{param}"` (true+ * when the value is), `"{param} == value"` or `"{param} != value"`. Mirrors+ * `holds` in core's template_v2. Something that is not a condition never holds.+ */+export function holds(condition: string | null | undefined, values: Values): boolean {+ if (condition === null || condition === undefined) return true;+ const match = /^\s*\{([A-Za-z_]\w*)\}\s*(?:(==|!=)\s*(.*?))?\s*$/.exec(condition);+ if (!match) return false;+ const [, name, op, literal] = match;+ const value = values[name!];+ if (!op) return value !== undefined && value !== '' && value !== false && value !== 0;+ const equal =+ value !== undefined && String(value) === (literal ?? '').trim().replace(/^['"]|['"]$/g, '');+ return op === '==' ? equal : !equal;}/** Every `{name}` placeholder written in `text`, without the braces. */@@ -50,6 +68,8 @@ export function paramLabel(param: ParamSpec): string {return 'Provider';case 'location':return 'Runs on';+ case 'machine':+ return 'Machine';case 'directory':return 'Directory';case 'room':@@ -166,23 +186,35 @@ export function resolveChain(return null;}-/** Which section of the page a param belongs to: the agent it is written- * into, or the room part. A `room` param always sits with the room, since- * it says where the agent works; a param used by both sits with the agent. */-export function sectionOf(- param: ParamSpec,- agentTexts: string[][],+/** What a document is missing for one of its agents, in one sentence. */+export function unsaidMessage(unsaid: UnsaidRuntime): string {+ const what =+ unsaid.field === 'provider'+ ? `which coding agent runs ${unsaid.label}`+ : unsaid.field === 'location'+ ? `which machine ${unsaid.label} runs on`+ : `which directory ${unsaid.label} works in`;+ const fields = unsaid.field === 'location' ? ['location', 'machine'] : [unsaid.field];+ const said = fields.map((f) => `\`${f}:\``).join(' or ');+ const params = fields.map((f) => `\`${f}\``).join(' or ');+ return `The template never says ${what}. Give it a ${said} or declare a ${params} param.`;+}++/**+ * The params only the room part reads: written into the room document and+ * into no agent entry. They do nothing when the room is not created.+ */+export function roomOnlyParams(+ params: ParamSpec[],+ agents: Pick<ParsedAgentEntry, 'placeholders'>[],roomText: string-): { section: 'agent'; index: number } | { section: 'room' } {- if (param.type !== 'room') {- const index = agentTexts.findIndex((texts) =>- texts.some((t) => placeholdersIn(t).includes(param.name))- );- if (index >= 0) return { section: 'agent', index };- }- if (param.type === 'room' || placeholdersIn(roomText).includes(param.name))- return { section: 'room' };- return { section: 'agent', index: 0 };+): Set<string> {+ const inRoom = new Set(placeholdersIn(roomText));+ return new Set(+ params+ .filter((p) => inRoom.has(p.name) && !agents.some((a) => a.placeholders.includes(p.name)))+ .map((p) => p.name)+ );}export type CreateStepStatus = 'waiting' | 'running' | 'done' | 'failed';@@ -194,6 +226,8 @@ export type CreateStep = {status: CreateStepStatus;/** A problem that did not stop the run, such as a repository that could not be cloned. */warning?: string | null;+ /** Why the step failed, when it says. */+ error?: string | null;};export function createStepStatus(status: SlotStatus): CreateStepStatus {@@ -220,8 +254,23 @@ export function agentCreateSteps(clones: boolean;setsPolicy: boolean;cloneWarning: string | null;+ /** A managed agent: the server makes it, its directory and who may address it in one call, on `machine`. */+ managed: { machine: string | null } | null;+ error: string | null;}): CreateStep[] {+ if (agent.managed) {+ return [+ {+ key: `${index}:create`,+ label: agent.managed.machine+ ? `Create ${agent.name} on ${agent.managed.machine}`+ : `Create ${agent.name}`,+ status: createStepStatus(agent.status),+ error: agent.status === 'failed' ? agent.error : null,+ },+ ];+ }const order: SlotStep[] = agent.setsPolicy? ['prepare', 'create', 'policy']: ['prepare', 'create'];@@ -245,5 +294,6 @@ export function agentCreateSteps(? 'done': createStepStatus(agent.status),warning: step === 'prepare' ? agent.cloneWarning : null,+ error: k === at && agent.status === 'failed' ? agent.error : null,}));}diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-servers/room-template-params.ts b/console/apps/switch-console-desktop/src/shared/core/switch-servers/room-template-params.tsindex c72658e21..1149d78a6 100644--- a/console/apps/switch-console-desktop/src/shared/core/switch-servers/room-template-params.ts+++ b/console/apps/switch-console-desktop/src/shared/core/switch-servers/room-template-params.ts@@ -9,11 +9,13 @@export const ENTITY_PARAM_TYPES = ['agent', 'bridge', 'room', 'user'] as const;export type EntityParamType = (typeof ENTITY_PARAM_TYPES)[number];-/** Param types the Console answers itself and leaves out of the request to- * the server. `provider` is the coding agent that runs an agent the template- * creates, `location` the machine it runs on, `directory` its working- * directory. Mirrors `CONSOLE_PARAM_TYPES` in core. */-export const CONSOLE_PARAM_TYPES = ['provider', 'location', 'directory'] as const;+/** Param types that say how an agent the template creates runs, left out of+ * the room document the server provisions. `provider` is the coding agent+ * that runs it; `location` where it runs as this Console knows it (this+ * computer or an SSH host), `machine` one of the owner's machines on the+ * server; `directory` its working directory. Mirrors `CONSOLE_PARAM_TYPES`+ * in core. */+export const CONSOLE_PARAM_TYPES = ['provider', 'location', 'machine', 'directory'] as const;export type ConsoleParamType = (typeof CONSOLE_PARAM_TYPES)[number];export type ParamType =@@ -50,6 +52,7 @@ export const CHAIN_PARAM_TYPES: readonly ParamType[] = ['room','provider','location',+ 'machine',];/** In a chain: the first thing of the param's type the server or the Console has. */diff --git a/console/packages/agent-controller/src/agent-hub.test.ts b/console/packages/agent-controller/src/agent-hub.test.tsindex d11a11ec0..c34dec8a8 100644--- a/console/packages/agent-controller/src/agent-hub.test.ts+++ b/console/packages/agent-controller/src/agent-hub.test.ts@@ -130,6 +130,35 @@ describe('handing events to the watcher', () => {expect(seen.connected).toBe(1);});+ it("hands a new agent's first watcher what arrived while it was starting", async () => {+ hub.streamAttached();+ hub.attach(AGENT, 0, ['room-a']);+ // A template's kickoff, posted the moment the agent exists, before its+ // host is up and with no cursor of its own.+ hub.ingest(message(1, true));+ const { stream, seen } = watcher();+ stream.start();+ await waitFor(() => seen.events.length === 1, 'the kickoff');+ expect(seen.events[0]!.sequence).toBe(1);+ expect(seen.gaps).toEqual([]);+ });++ it('starts a later watcher with no cursor at the newest event, as before', async () => {+ hub.streamAttached();+ hub.attach(AGENT, 0, ['room-a']);+ const first = watcher();+ first.stream.start();+ hub.ingest(message(1, true));+ await waitFor(() => first.seen.events.length === 1, 'the first event');+ first.stop();+ hub.ingest(message(2, true));+ const second = watcher();+ second.stream.start();+ hub.ingest(message(3, true));+ await waitFor(() => second.seen.events.length === 1, 'the event after it started');+ expect(second.seen.events[0]!.sequence).toBe(3);+ });+it('tells a watcher starting from before what is held that it missed events', async () => {hub.streamAttached();hub.attach(AGENT, 0, ['room-a']);diff --git a/console/packages/agent-controller/src/agent-hub.ts b/console/packages/agent-controller/src/agent-hub.tsindex b0270850b..42ef8308f 100644--- a/console/packages/agent-controller/src/agent-hub.ts+++ b/console/packages/agent-controller/src/agent-hub.ts@@ -67,6 +67,15 @@ type AgentState = {rooms: Set<string> | null;/** The highest sequence known for this agent. */head: number | null;+ /**+ * Where Switch first attached the agent to this controller. An agent host+ * that starts with no cursor of its own (a new agent's first run) starts+ * here, so what addressed the agent while its host was coming up (a+ * template's kickoff, posted the moment the agent exists) is not skipped.+ */+ attachedFrom: number | null;+ /** An agent host has started for it since the controller started. */+ hostStarted: boolean;/** At or below this, nothing is held: an agent host starting there is told of a gap. */droppedThrough: number;/** The cursor the controller resumes the agent from upstream. */@@ -198,6 +207,7 @@ export class AgentHub {const agent = this.agent(agentId);agent.attached = true;agent.rooms = new Set(rooms);+ if (agent.attachedFrom === null) agent.attachedFrom = fromSeq;if (agent.head === null) agent.head = fromSeq;else if (fromSeq > agent.head) {// Switch starts the agent past what is held here: whatever lay between@@ -387,7 +397,10 @@ export class AgentHub {start: () => {if (host.started || host.closed) return;host.started = true;- host.cursor = deps.startCursor ?? agent.head;+ host.cursor =+ deps.startCursor ??+ (!agent.hostStarted && agent.attachedFrom !== null ? agent.attachedFrom : agent.head);+ agent.hostStarted = true;if (agent.reset &&host.cursor !== null &&@@ -436,6 +449,8 @@ export class AgentHub {attached: false,rooms: null,head: null,+ attachedFrom: null,+ hostStarted: false,droppedThrough: 0,confirmed: null,buffer: [],diff --git a/console/packages/agent-providers/src/host/agent-host.ts b/console/packages/agent-providers/src/host/agent-host.tsindex 8d5e45a08..d92bc923a 100644--- a/console/packages/agent-providers/src/host/agent-host.ts+++ b/console/packages/agent-providers/src/host/agent-host.ts@@ -757,6 +757,29 @@ export async function runAgentHost(})));+ /**+ * Per session, the messages handed to it and not yet acknowledged, sent+ * down the IPC pipe one at a time and in order. Each is parked in the+ * journal first and released on the host's acknowledgement, so one this+ * controller dies holding is routed again when it restarts.+ *+ * `failed` is set when the host stopped on a failure it recorded, or+ * would not take a message however often it was started again: the+ * messages stay queued and the host is not started again until something+ * changes — another room message for it, or its host coming up because+ * somebody started it from Console. `restarts` counts the starts in a row+ * that did not get the first queued message taken.+ */+ type Pump = {+ queue: Handoff[];+ running: boolean;+ failed: string | null;+ restarts: number;+ config: SharedHostConfig;+ };+ // Declared before the ready listener below reads it: another session can+ // come up while this host is still awaiting its own start-up.+ const pumps = new Map<string, Pump>();// A host coming up — started from Console after it failed, say — takes// the messages that waited for it.unbind.push(@@ -899,27 +922,6 @@ export async function runAgentHost();}};- /**- * Per session, the messages handed to it and not yet acknowledged, sent- * down the IPC pipe one at a time and in order. Each is parked in the- * journal first and released on the host's acknowledgement, so one this- * controller dies holding is routed again when it restarts.- *- * `failed` is set when the host stopped on a failure it recorded, or- * would not take a message however often it was started again: the- * messages stay queued and the host is not started again until something- * changes — another room message for it, or its host coming up because- * somebody started it from Console. `restarts` counts the starts in a row- * that did not get the first queued message taken.- */- type Pump = {- queue: Handoff[];- running: boolean;- failed: string | null;- restarts: number;- config: SharedHostConfig;- };- const pumps = new Map<string, Pump>();const pump = (config: SharedHostConfig) => {const sessionId = config.session.sessionId;const entry = pumps.get(sessionId)!;diff --git a/console/packages/plugins/src/switch-skill/SKILL.md b/console/packages/plugins/src/switch-skill/SKILL.mdindex f3ebc7d3f..cf99b7738 100644--- a/console/packages/plugins/src/switch-skill/SKILL.md+++ b/console/packages/plugins/src/switch-skill/SKILL.md@@ -470,23 +470,32 @@ carrying a display name addresses no one.Templates saved on the workspace can be found, read, run and saved by you.Before writing one, call **`get_template_guide`**: the template language and-the schema the server checks documents against.+the schema the server checks documents against. Write new templates in its+version 2: every resource under `resources:` with a key and a `type`,+resources naming each other by key, and `if:` as the one conditional.- **`list_templates`**: what you can use, every shared template plus yourowner's private ones. Each row says who saved it and `can_edit`.- **`get_template`**: one template's document, its `params` (the inputs to- fill) and `agent_slots` (the agents it would create).-- **`run_template`**: create the rooms a saved template describes, like- `create_room_from_yaml`. You cannot create agents; an agent or team- template runs when you fill each slot with an existing agent, in- `agents: {slot name: agent name}`.+ fill) and `agent_slots` (the agents it would create, each with its+ machine, provider, model, connections and whether an existing agent may+ stand in).+- **`run_template`**: create the agents and rooms a saved template+ describes. Each agent is created as a managed agent of your owner on the+ machine its entry names, which needs "can manage agents"; a slot whose+ entry says `allow_existing: true` can take an existing agent instead, in+ `agents: {slot name: agent name}`. Everything is checked first and nothing+ is created on a refusal; agents made before a later failure are deleted+ again. Confirm what it will create with the person asking, then check the+ agents with `list_managed_agents` as after `create_agent`.- **`save_template`**: save a template for your owner, `private` or`shared`. Only you can change or delete it afterwards.- **`update_template`** / **`delete_template`**: only for templates you saved.-A refusal says why (a template you did not save, a slot that needs a new-agent, a name your owner already uses). Tell the person who asked, and what-they can do instead.+A refusal says why, with a reason code per agent (a template you did not+save, a machine that is offline or lacks the provider, a connection your+owner has not made, a name already taken). Tell the person who asked, and+what they can do instead.### Room documents and attached resources@@ -934,7 +943,7 @@ Every Switch tool you call in normal operation, one line each.- `get_template_guide`: how to write a template, and the schema it is checked against.- `list_templates`: the saved templates you can use.- `get_template`: one template's document, inputs and agent slots.-- `run_template`: create the rooms a saved template describes.+- `run_template`: create the agents and rooms a saved template describes.- `save_template`: save a template, private or shared.- `update_template`: change a template you saved.- `delete_template`: delete a template you saved.diff --git a/core/switch_core/agent_refusals.py b/core/switch_core/agent_refusals.pyindex be74b65fe..b8d491fa5 100644--- a/core/switch_core/agent_refusals.py+++ b/core/switch_core/agent_refusals.py@@ -1,7 +1,8 @@"""Requests the server refuses an agent, and how the refusal is reported.An agent acts for its owner, but not with everything the owner may do: it may-change only the templates it saved, it cannot create agents, and the run+change only the templates it saved, it creates agents only with its owner's+leave and on its owner's machines, and the runguards in ``agent_runs`` refuse rooms that cannot work. When one of thoserules says no, the agent gets a sentence it can act on, and the refusal isreported. Nobody yet knows which of these rules people will run into, so the@@ -32,8 +33,11 @@ RefusalReason = Literal["visibility_not_allowed","invalid","too_large",+ "has_warnings","missing_agents","agent_creation_console_only",+ "agents_not_created",+ "run_undone",# Rooms an agent creates (see `agent_runs`)"busy","run_paused",diff --git a/core/switch_core/agent_runs.py b/core/switch_core/agent_runs.pyindex 45217ff3b..61e84778b 100644--- a/core/switch_core/agent_runs.py+++ b/core/switch_core/agent_runs.py@@ -17,7 +17,7 @@ from collections.abc import AsyncIteratorfrom contextlib import asynccontextmanagerfrom dataclasses import dataclass, replacefrom datetime import datetime-from typing import TYPE_CHECKING, Literal, cast+from typing import TYPE_CHECKING, Any, Literal, castfrom pydantic import BaseModelfrom sqlalchemy import func, select@@ -158,6 +158,7 @@ class RunService:owner_name: str | None,from_room_id: str | None,kickoffs: list[tuple[str, list[str], dict[str, str]]] | None = None,+ pending: dict[str, tuple[dict[str, Any] | None, str]] | None = None,) -> AsyncIterator[AgentOrigin]:"""Hold the agent's one creation slot while its rooms are made.@@ -165,13 +166,16 @@ class RunService:caller creates anything, so a request is made whole or not at all.``kickoffs`` lists each kickoff the request would post, with theagents in its room and their aliases (agent name to alias).+ ``pending`` names the agents the request creates before its rooms,+ with the addressing policy each will have and its owner, so a kickoff+ is checked against them too."""async with self._one_at_a_time(agent.id):origin = await self._origin(agent, owner_name, from_room_id)await self._check_open(origin)hashes = [kickoff_fingerprint(text) for text, _, _ in kickoffs or []]await self._check_repeat(origin, hashes)- await self._check_audience(agent, kickoffs or [])+ await self._check_audience(agent, kickoffs or [], pending or {})if kickoffs:origin = replace(origin, trace=await self._trace(origin))yield origin@@ -292,7 +296,10 @@ class RunService:)async def _check_audience(- self, agent: Agent, kickoffs: list[tuple[str, list[str], dict[str, str]]]+ self,+ agent: Agent,+ kickoffs: list[tuple[str, list[str], dict[str, str]]],+ pending: dict[str, tuple[dict[str, Any] | None, str]],) -> None:"""Every agent a kickoff mentions must accept this agent, or the roomwould be made and nobody would start work in it."""@@ -304,10 +311,18 @@ class RunService:text, name, aliases.get(name)):continue- target = await self._agent_store.get_by_name(session, name)- if target is None:- continue- policy = parse_policy(target.addressing_policy)+ target_owner_id: str | None+ if name in pending:+ stored, target_owner_id = pending[name]+ else:+ target = await self._agent_store.get_by_name(session, name)+ if target is None:+ continue+ stored, target_owner_id = (+ target.addressing_policy,+ target.owner_id,+ )+ policy = parse_policy(stored)if policy.is_open() or can_address(policy,# A rule scoped to a room or group cannot name a room@@ -318,22 +333,41 @@ class RunService:sender_id=agent.id,sender_user_ids=[],sender_owner_user_id=agent.owner_id,- owner_user_id=target.owner_id,+ owner_user_id=target_owner_id,):continueif name not in refused:refused.append(name)- if refused:- listed = ", ".join(refused)- raise RunRefused(- "kickoff_ignored",- f"Nothing was created: the kickoff mentions {listed}, and "- f"{'it does' if len(refused) == 1 else 'they do'} not accept "- f"messages from {agent.name}, so nobody would start work in the "- f"room. Ask their owner to let {agent.name} address them (in "- f"Switch Console, the agent's 'Who can talk to your agent'), or "- f"leave them out of the kickoff.",+ if not refused:+ return+ created = [name for name in refused if name in pending]+ existing = [name for name in refused if name not in pending]+ reasons: list[str] = []+ if existing:+ listed = ", ".join(existing)+ reasons.append(+ f"the kickoff mentions {listed}, and "+ f"{'it does' if len(existing) == 1 else 'they do'} not accept "+ f"messages from {agent.name}. Ask their owner to let {agent.name} "+ "address them (in Switch Console, the agent's 'Who can talk to "+ "your agent'), or leave them out of the kickoff"+ )+ if created:+ listed = ", ".join(created)+ reasons.append(+ f"the kickoff mentions {listed}, which this run creates answering "+ f"only its owner, so {agent.name}'s kickoff would not reach "+ f"{'it' if len(created) == 1 else 'them'}. Give "+ f"{'its entry' if len(created) == 1 else 'their entries'} "+ "`addressing: owner-agents` (or `anyone`) in the template, or "+ "leave them out of the kickoff")+ raise RunRefused(+ "kickoff_ignored",+ "Nothing was created: "+ + "; ".join(reasons)+ + ". Nobody would start work in the room (kickoff_ignored).",+ )async def _trace(self, origin: AgentOrigin) -> str | None:"""The run so far, top down, as the woken agents are shown it."""diff --git a/core/switch_core/agent_template_ops.py b/core/switch_core/agent_template_ops.pyindex b195d7531..e8bb42fc1 100644--- a/core/switch_core/agent_template_ops.py+++ b/core/switch_core/agent_template_ops.py@@ -14,7 +14,7 @@ operation layer reports (see ``agent_refusals``).from __future__ import annotations-from dataclasses import dataclass+from dataclasses import asdict, dataclassfrom typing import TYPE_CHECKING, Any, Literalimport yaml@@ -24,6 +24,13 @@ from switch_core.agent_templates import agent_slots, template_kindfrom switch_core.authz import Principal, canfrom switch_core.db.models import Agent, Template, Userfrom switch_core.db.stores.template_store import TemplateNameTaken, TemplateStore+from switch_core.official_templates import (+ OfficialTemplate,+ is_official,+ matches,+ official_template,+ official_templates,+)from switch_core.template_lint import lint_templateif TYPE_CHECKING:@@ -57,6 +64,8 @@ def _visibility(template: Template | Any) -> str:async def _saved_by(session: AsyncSession, template: Template | Any) -> str:+ if isinstance(template, OfficialTemplate):+ return "Switch"if template.created_by_agent_id:agent = await session.get(Agent, template.created_by_agent_id)return f"agent {agent.name}" if agent else "an agent that no longer exists"@@ -82,6 +91,7 @@ def _params(content: str) -> list[dict[str, Any]]:"description": spec.get("description"),"default": spec.get("default"),"required": spec.get("required"),+ "if": spec.get("if"),}for name, spec in raw.items()if isinstance(spec, dict)@@ -89,9 +99,13 @@ def _params(content: str) -> list[dict[str, Any]]:class AgentTemplates:- def __init__(self, store: TemplateStore, *, max_bytes: int) -> None:+ def __init__(+ self, store: TemplateStore, *, max_bytes: int, agent_management: bool+ ) -> None:self._store = storeself._max_bytes = max_bytes+ # Which document an official template that comes in two is served as.+ self._agent_management = agent_management# ── Reading ───────────────────────────────────────────────────────────@@ -106,7 +120,20 @@ class AgentTemplates:rows = await self._store.list_all(session, viewer_id=acting.owner.id, is_admin=False, query=query, kind=kind)- return [+ official = [+ {+ "id": t.id,+ "name": t.name,+ "description": t.description,+ "kind": t.kind,+ "visibility": "shared",+ "saved_by": "Switch",+ "can_edit": False,+ }+ for t in official_templates(self._agent_management)+ if matches(t, query, kind)+ ]+ return official + [{"id": row.id,"name": row.name,@@ -121,9 +148,19 @@ class AgentTemplates:async def load(self, session: AsyncSession, acting: ActingFor, template_id: str- ) -> Template:+ ) -> Template | OfficialTemplate:"""A template the agent may read, or ``not_found``: one it may not- read does not exist for it, as for a person."""+ read does not exist for it, as for a person. An ``official:`` id is+ one that comes with Switch."""+ if is_official(template_id):+ official = official_template(template_id, self._agent_management)+ if official is None:+ raise AgentRefused(+ "not_found",+ f"No template with id {template_id}. list_templates shows the "+ "ones you can use.",+ )+ return officialtemplate = await self._store.get(session, template_id)if template is None or not can(acting.reader, "read", template):raise AgentRefused(@@ -138,10 +175,7 @@ class AgentTemplates:) -> dict[str, Any]:template = await self.load(session, acting, template_id)try:- slots = [- {"name": s.name, "description": s.description}- for s in agent_slots(template.content)- ]+ slots = [asdict(s) for s in agent_slots(template.content)]except ValueError:slots = []return {@@ -159,7 +193,12 @@ class AgentTemplates:# ── Writing ───────────────────────────────────────────────────────────- def _check_content(self, content: str) -> str:+ def _check_content(+ self, content: str, *, bypass_warnings: bool+ ) -> tuple[str, list[str]]:+ """The document's kind and its lint warnings, refusing a document no+ consumer could provision, and one with warnings unless the agent has+ seen them and chosen to save anyway."""size = len(content.encode("utf-8"))if size > self._max_bytes:raise AgentRefused(@@ -175,9 +214,19 @@ class AgentTemplates:+ "; ".join(f.message for f in lint.errors if f.blocking),)try:- return template_kind(content)+ kind = template_kind(content)except ValueError as e:raise AgentRefused("invalid", str(e)) from e+ warnings = [f.message for f in lint.warnings]+ if warnings and not bypass_warnings:+ raise AgentRefused(+ "has_warnings",+ "The template was not saved, because of these warnings: "+ + " ".join(f"({i}) {w}" for i, w in enumerate(warnings, 1))+ + " Fix them, or tell whoever asked for the template what they "+ "mean and save again with bypass_warnings=true.",+ )+ return kind, warnings@staticmethoddef _pair(visibility: str) -> tuple[str, str]:@@ -209,9 +258,10 @@ class AgentTemplates:description: str,content: str,visibility: str,- ) -> Template:+ bypass_warnings: bool,+ ) -> tuple[Template, list[str]]:read, write = self._pair(visibility)- kind = self._check_content(content)+ kind, warnings = self._check_content(content, bypass_warnings=bypass_warnings)try:template = await self._store.create(session,@@ -228,12 +278,18 @@ class AgentTemplates:)except TemplateNameTaken as e:raise self._name_taken(name) from e- return template+ return template, warningsasync def _own(self, session: AsyncSession, acting: ActingFor, template_id: str) -> Template:template = await self.load(session, acting, template_id)+ if isinstance(template, OfficialTemplate):+ raise AgentRefused(+ "not_yours",+ f"'{template.name}' comes with Switch, so nobody can change or "+ "delete it. Save your own version under another name instead.",+ )if template.created_by_agent_id != acting.agent.id:raise AgentRefused("not_yours",@@ -254,13 +310,18 @@ class AgentTemplates:description: str | None,content: str | None,visibility: str | None,- ) -> Template:+ bypass_warnings: bool,+ ) -> tuple[Template, list[str]]:template = await self._own(session, acting, template_id)label = name or template.nameread, write = self._pair(visibility) if visibility is not None else (None, None)- kind = self._check_content(content) if content is not None else None+ kind, warnings = (+ self._check_content(content, bypass_warnings=bypass_warnings)+ if content is not None+ else (None, [])+ )try:- return await self._store.update_fields(+ updated = await self._store.update_fields(session,template.id,name=name,@@ -273,6 +334,7 @@ class AgentTemplates:)except TemplateNameTaken as e:raise self._name_taken(label) from e+ return updated, warnings@staticmethoddef _still_own(acting: ActingFor, locked: Template) -> None:diff --git a/core/switch_core/agent_templates.py b/core/switch_core/agent_templates.pyindex 9a114101b..747f8af44 100644--- a/core/switch_core/agent_templates.py+++ b/core/switch_core/agent_templates.py@@ -3,13 +3,14 @@The registry keeps documents verbatim and never parses them. When an agentasks what a template is, or asks to run one, something has to: this modulesays which kind a document is, which agents it would create, and how to turn-an agent or team template into a room document the server can provision.--The server never creates agents; the Console does, on the machine the agent-runs on. So an agent or team template is runnable here only when every agent-it describes is swapped for an agent that already exists, the way the-Console's Use page does it for "Existing agent". The ``agent:``/``agents:``-block is then dropped and the room half runs like any room template.+an agent or team template into the agents to create and the room document+the server provisions after them.++Each agent a template describes is either created, as a managed agent on one+of the owner's machines (`plan_template`, then `template_runs`), or, where+the entry says `allow_existing: true`, filled with an agent that already+exists. Either way the ``agent:``/``agents:`` block is then dropped and the+room half runs like any room template, naming the agents by their names."""from __future__ import annotations@@ -21,15 +22,23 @@ from typing import Any, Literalimport yamlfrom pydantic import ValidationError-from switch_core.agent_refusals import AgentRefusedfrom switch_core.rooms_yaml import (CONSOLE_PARAM_TYPES,ENTITY_PARAM_TYPES,+ FIRST,PLACEHOLDER_RE,ParamSpec,coerce_param,interpolate,)+from switch_core.template_runs import (+ AGENTS_DIR,+ AgentsNotCreated,+ ConnectionPlan,+ NewAgentPlan,+ Problem,+)+from switch_core.template_v2 import compile_v2, is_v2TemplateKind = Literal["room", "group", "agent"]@@ -55,6 +64,16 @@ def template_kind(text: str) -> TemplateKind:(``kindOf``): a ``group:`` or ``rooms:`` makes a group, then severalagents a group, one agent an agent template, anything else a room."""data = _load(text)+ if is_v2(data):+ resources = data.get("resources")+ kinds = [+ spec.get("type")+ for spec in (resources.values() if isinstance(resources, dict) else [])+ if isinstance(spec, dict)+ ]+ if "group" in kinds or kinds.count("room") > 1 or kinds.count("agent") > 1:+ return "group"+ return "agent" if "agent" in kinds else "room"if "group" in data or isinstance(data.get("rooms"), list):return "group"agents = _agents(data)@@ -91,21 +110,114 @@ def _resolved_name(agent: dict[str, Any], values: dict[str, Any]) -> str:@dataclass(frozen=True)class AgentSlot:- """An agent a template would create, which a run fills with an agent- that already exists. ``name`` is as the template writes it, placeholders- and all."""+ """An agent a template describes: created by a run, or, where+ ``allow_existing`` is true, filled with one that already exists. Fields+ are as the template writes them, placeholders and all, a setting said for+ every agent by a param no entry reads shown as that ``{param}``; None+ where it says nothing."""name: strdescription: str | None+ allow_existing: bool+ # A version 2 resource's key, and the condition it is created under.+ key: str | None+ condition: str | None+ provider: str | None+ machine: str | None+ location: str | None+ model: str | None+ directory: str | None+ connections: list[dict[str, Any]]+++def _written(entry: dict[str, Any], key: str) -> str | None:+ value = entry.get(key)+ return None if value is None else str(value)+++def _slot_connections(entry: dict[str, Any]) -> list[dict[str, Any]]:+ raw = entry.get("connections")+ out: list[dict[str, Any]] = []+ for item in raw if isinstance(raw, list) else []:+ if isinstance(item, dict):+ repos = item.get("repos") or []+ out.append(+ {+ "service": str(item.get("service")),+ "access": item.get("access"),+ "repos": [+ str(r) for r in (repos if isinstance(repos, list) else [repos])+ ],+ }+ )+ else:+ out.append({"service": str(item), "access": None, "repos": []})+ return out+++def _v2_slots(data: dict[str, Any]) -> list[AgentSlot]:+ resources = data.get("resources")+ slots = []+ for key, spec in resources.items() if isinstance(resources, dict) else []:+ if not isinstance(spec, dict) or spec.get("type") != "agent":+ continue+ slots.append(+ AgentSlot(+ name=_written_name(spec),+ description=str(spec["description"])+ if spec.get("description")+ else None,+ allow_existing=spec.get("allow_existing") is True,+ key=str(key),+ condition=_written(spec, "if"),+ provider=_written(spec, "provider"),+ machine=_written(spec, "machine"),+ location=_written(spec, "location"),+ model=_written(spec, "model"),+ directory=_written(spec, "directory"),+ connections=_slot_connections(spec),+ )+ )+ return slots+++def repo_note(repo: str) -> str:+ """What an agent created from a template with a ``repo`` is told: to+ clone it into its directory. Access to a private one comes from a+ connection the template lists, or the machine's own credentials."""+ return (+ f"\n\nYou work on the repository {repo}. If your working directory is "+ f"not a clone of it yet, clone {repo} into it first."+ )def agent_slots(text: str) -> list[AgentSlot]:+ data = _load(text)+ if is_v2(data):+ return _v2_slots(data)+ planner = _Planner(data, {}, None)++ def said(entry: dict[str, Any], key: str) -> str | None:+ if entry.get(key) is not None:+ return str(entry[key])+ shared = planner.for_all(key)+ return f"{{{shared}}}" if shared else None+return [AgentSlot(name=_written_name(a),description=str(a["description"]) if a.get("description") else None,+ allow_existing=a.get("allow_existing") is True,+ key=None,+ condition=None,+ provider=said(a, "provider"),+ machine=said(a, "machine"),+ location=said(a, "location"),+ model=_written(a, "model"),+ directory=said(a, "directory"),+ connections=_slot_connections(a),)- for a in _agents(_load(text))+ for a in planner.entries]@@ -164,6 +276,17 @@ def _placeholders(node: Any, into: set[str]) -> set[str]:return into+def _room_part(data: dict[str, Any]) -> dict[str, Any] | None:+ """The keys the server provisions rooms from, or None for a document+ that describes no room."""+ part = {+ k: data[k] for k in ("room", "group", "rooms", "links", "kickoff") if k in data+ }+ if not part.get("room") and "group" not in part and "rooms" not in part:+ return None+ return part++def room_document(text: str, filled: dict[str, str], inputs: dict[str, Any]) -> tuple[str, dict[str, Any]]:@@ -171,10 +294,9 @@ def room_document(create replaced by the existing agent that fills its slot.``filled`` maps a slot, by the name the template writes or the name it- resolves to with ``inputs``, to an existing agent's name. Returns the- document and the inputs to run it with. A document with no agents is- returned as it is. A slot left empty is refused: creating an agent is the- Console's to do.+ resolves to with ``inputs``, to the name of the agent standing in it: an+ existing one, or the one the run creates. Returns the document and the+ inputs to run it with. A document with no agents is returned as it is."""data = _load(text)agents = _agents(data)@@ -195,27 +317,11 @@ def room_document(if key:replacements[key] = chosenif unfilled:- raise AgentRefused(- "agent_creation_console_only",- "Nothing was created: this template creates "- f"{', '.join(unfilled)}, and creating agents happens in Switch "- "Console. To run it here, fill each with an agent that already "- "exists, in `agents`: {slot name: agent name}.",- )+ raise ValueError(f"No agent named for {', '.join(unfilled)}")- room_part = {- k: data[k] for k in ("room", "group", "rooms", "links", "kickoff") if k in data- }- if (- not room_part.get("room")- and "group" not in room_part- and "rooms" not in room_part- ):- raise AgentRefused(- "agent_creation_console_only",- "Nothing was created: this template only creates an agent, with no "- "room to run. Creating agents happens in Switch Console.",- )+ room_part = _room_part(data)+ if room_part is None:+ raise ValueError("The template has no room to provision")if isinstance(data.get("agent"), dict):# A one-agent template names its agent `{agent}` in the room, a value# the Console supplies. Here it is the agent that fills the slot.@@ -284,3 +390,552 @@ def room_document(out["params"] = paramsout.update(room_part)return yaml.safe_dump(out, sort_keys=False, allow_unicode=True), run_inputs+++# ── Planning a run on the server ──────────────────────────────────────────++_AGENT_ADDRESSING = ("owner", "owner-agents", "anyone")+++@dataclass(frozen=True)+class TemplatePlan:+ """What running a template creates: the agents, by slot, and the room+ document after them (None when the template describes no room), with the+ inputs to provision it with. ``existing`` maps each slot filled with an+ agent that already exists to that agent's name."""++ new_agents: list[NewAgentPlan]+ existing: dict[str, str]+ document: str | None+ inputs: dict[str, Any]+ # Per agent created, the rooms (by name) whose members may address it+ # beyond its owner: a version 2 `addressing: {anyone_in: [...]}`.+ room_addressing: dict[str, list[str]]+++def _machine_ready(machine: dict[str, Any], provider: str | None) -> bool:+ if machine.get("state") != "online":+ return False+ if provider is None:+ return True+ return any(+ entry.get("provider") == provider+ and entry.get("installed")+ and entry.get("auth") not in ("missing", "expired")+ for entry in machine.get("providers") or []+ )+++def _why_not_ready(machine: dict[str, Any], providers: set[str]) -> str:+ name = str(machine.get("name"))+ state = machine.get("state")+ if state != "online":+ return f"{name} is {state}"+ entries = {str(e.get("provider")): e for e in machine.get("providers") or []}+ for provider in sorted(providers):+ entry = entries.get(provider)+ if entry is None or not entry.get("installed"):+ return f"{provider} is not installed on {name}"+ if entry.get("auth") in ("missing", "expired"):+ return f"{provider} is not signed in on {name}"+ return f"{name} cannot take it"+++def _find_machine(machines: list[dict[str, Any]], ref: str) -> dict[str, Any] | None:+ by_id = next((m for m in machines if m.get("id") == ref), None)+ if by_id is not None:+ return by_id+ named = [m for m in machines if m.get("name") == ref]+ return named[0] if len(named) == 1 else None+++def _ready_providers(machine: dict[str, Any] | None) -> list[str]:+ if machine is None:+ return []+ return [+ str(entry["provider"])+ for entry in machine.get("providers") or []+ if entry.get("installed") and entry.get("auth") not in ("missing", "expired")+ ]+++class _Planner:+ """Resolves each agent entry to what it creates, collecting every problem+ rather than stopping at the first."""++ def __init__(+ self,+ data: dict[str, Any],+ values: dict[str, Any],+ machines: list[dict[str, Any]] | None,+ ) -> None:+ self.data = data+ self.values = values+ self.machines = machines+ raw = data.get("params")+ self.params: dict[str, dict[str, Any]] = {+ k: v+ for k, v in (raw if isinstance(raw, dict) else {}).items()+ if isinstance(v, dict)+ }+ self.entries = _agents(data)+ self.problems: list[Problem] = []+ self.room_inputs: dict[str, str] = {}+ # Why `$first` found no machine, one line per machine the owner has.+ self.unready: list[str] = []++ def field_texts(self) -> list[str]:+ return [+ str(entry[key])+ for entry in self.entries+ for key in ("provider", "location", "machine", "directory")+ if entry.get(key) is not None+ ]++ def for_all(self, kind: str) -> str | None:+ """The param of type ``kind`` that no entry's field reads, which says+ it for every agent."""+ texts = self.field_texts()+ for name, spec in self.params.items():+ if spec.get("type") == kind and not any(+ f"{{{name}}}" in text for text in texts+ ):+ return name+ return None++ def chain(self, name: str) -> list[str]:+ default = self.params.get(name, {}).get("default")+ if isinstance(default, list):+ return [str(c) for c in default]+ return [] if default is None else [str(default)]++ def providers_on(self, name: str) -> set[str]:+ """The providers the agents a machine param places say outright:+ what the machine it resolves to must be able to run."""+ shared = self.for_all("machine") == name+ wanted: set[str] = set()+ for entry in self.entries:+ field_ = entry.get("machine")+ if field_ == f"{{{name}}}" or (field_ is None and shared):+ provider = entry.get("provider")+ text = (+ str(interpolate(provider, self.values))+ if provider is not None+ else ""+ )+ if text and not PLACEHOLDER_RE.search(text):+ wanted.add(text)+ return wanted++ def resolve_machine_param(self, name: str) -> str | None:+ """A machine param's value, one for every agent it places: as given,+ else the first candidate of its default the owner has (``$first``:+ the first online machine that can run all their providers)."""+ if name in self.values:+ return str(self.values[name])+ if self.machines is None:+ return None+ ordered = sorted(self.machines, key=lambda m: str(m.get("name")))+ providers = self.providers_on(name)+ for candidate in self.chain(name):+ if candidate == FIRST:+ ready = next(+ (+ m+ for m in ordered+ if _machine_ready(m, None)+ and all(_machine_ready(m, p) for p in providers)+ ),+ None,+ )+ if ready is not None:+ self.values[name] = str(ready["id"])+ return str(ready["id"])+ self.unready = [_why_not_ready(m, providers) for m in ordered]+ continue+ found = _find_machine(self.machines, candidate)+ if found is not None:+ self.values[name] = str(found["id"])+ return str(found["id"])+ return None++ def first_machine(self, entry: dict[str, Any]) -> str | None:+ """``$first`` for one entry: the first online machine, by name, that+ can run the provider it says outright."""+ if self.machines is None:+ return None+ provider = entry.get("provider")+ text = str(interpolate(provider, self.values)) if provider is not None else ""+ wanted = {text} if text and not PLACEHOLDER_RE.search(text) else set()+ ordered = sorted(self.machines, key=lambda m: str(m.get("name")))+ ready = next(+ (+ m+ for m in ordered+ if _machine_ready(m, None) and all(_machine_ready(m, p) for p in wanted)+ ),+ None,+ )+ if ready is None:+ self.unready = [_why_not_ready(m, wanted) for m in ordered]+ return None+ return str(ready["id"])++ def resolve_provider_param(self, name: str, machine_ref: str | None) -> str | None:+ """A provider param's value: as given, else the first candidate of its+ default ready on the agent's machine (``$first``: the first ready)."""+ if name in self.values:+ return str(self.values[name])+ machine = (+ _find_machine(self.machines, machine_ref)+ if self.machines is not None and machine_ref is not None+ else None+ )+ ready = _ready_providers(machine)+ for candidate in self.chain(name):+ if candidate == FIRST:+ if ready:+ return ready[0]+ continue+ if machine is None or candidate in ready:+ return candidate+ return None++ def unready_text(self) -> str:+ if self.machines == []:+ return " (your owner has no machines)"+ return f" ({'; '.join(self.unready)})" if self.unready else ""++ def problem(self, slot: str, code: str, message: str) -> None:+ self.problems.append(Problem(slot, code, message))++ def text(self, slot: str, node: Any, values: dict[str, Any], what: str) -> Any:+ """``node`` with the values filled in; a placeholder left over names+ an input nobody gave."""+ result = interpolate(node, values)+ left = sorted(+ n+ for n in _placeholders(result, set())+ if not n.startswith("$") and n in self.params+ )+ if left:+ self.problem(+ slot,+ "input_missing",+ f"its {what} needs {', '.join(left)}, which has no value; give "+ "it in inputs.",+ )+ return result++ def plan(self, entry: dict[str, Any], slot: str) -> NewAgentPlan | None:+ before = len(self.problems)+ values = dict(self.values)+ name = _resolved_name(entry, values)+ values["agent"] = name++ provider_field = entry.get("provider")+ machine: str | None = None+ machine_field = entry.get("machine")+ if machine_field is not None:+ ref = PLACEHOLDER_RE.fullmatch(str(machine_field))+ if ref and self.params.get(ref.group(1), {}).get("type") == "machine":+ machine = self.resolve_machine_param(ref.group(1))+ if machine is None:+ self.problem(+ slot,+ "machine_unresolved",+ f"none of the machines its '{ref.group(1)}' input "+ "offers is one of your owner's machines that can take it"+ f"{self.unready_text()}; give a machine in inputs.",+ )+ else:+ machine = str(self.text(slot, machine_field, values, "machine"))+ elif (shared := self.for_all("machine")) is not None:+ machine = self.resolve_machine_param(shared)+ if machine is None:+ self.problem(+ slot,+ "machine_unresolved",+ f"none of the machines the '{shared}' input offers is one "+ f"of your owner's machines that can take it{self.unready_text()}; "+ "give a machine in inputs.",+ )+ elif entry.get("location") is not None or self.for_all("location"):+ # A location (this computer, an SSH host) is something a Console+ # knows, not the server: it names a machine only when it is one+ # of the owner's machines, and otherwise stands for `$first`.+ field_ = entry.get("location")+ if field_ is None:+ field_ = f"{{{self.for_all('location')}}}"+ written = str(interpolate(field_, values))+ found = (+ _find_machine(self.machines, written)+ if self.machines is not None and not PLACEHOLDER_RE.search(written)+ else None+ )+ machine = (+ str(found["id"]) if found is not None else self.first_machine(entry)+ )+ if machine is None:+ self.problem(+ slot,+ "machine_unresolved",+ f"none of your owner's machines can take it{self.unready_text()}.",+ )+ else:+ self.problem(+ slot,+ "machine_unsaid",+ "the template never says which machine it runs on. Give it a "+ "'machine:' or declare a 'machine' param.",+ )++ provider: str | None = None+ if provider_field is not None:+ ref = PLACEHOLDER_RE.fullmatch(str(provider_field))+ if ref and self.params.get(ref.group(1), {}).get("type") == "provider":+ provider = self.resolve_provider_param(ref.group(1), machine)+ else:+ provider = str(self.text(slot, provider_field, values, "provider"))+ elif (shared := self.for_all("provider")) is not None:+ provider = self.resolve_provider_param(shared, machine)+ else:+ self.problem(+ slot,+ "provider_unsaid",+ "the template never says which coding agent runs it. Give it a "+ "'provider:' or declare a 'provider' param.",+ )+ if provider is None and len(self.problems) == before:+ self.problem(+ slot,+ "provider_unresolved",+ "none of the coding agents its provider input offers is ready "+ "on its machine; give a provider in inputs.",+ )++ directory: str | None = None+ directory_field = entry.get("directory")+ if directory_field is None and (shared := self.for_all("directory")):+ directory_field = f"{{{shared}}}"+ if directory_field is None:+ self.problem(+ slot,+ "directory_unsaid",+ "the template never says which directory it works in. Give it "+ f"a 'directory:' ({AGENTS_DIR}/{{agent}} is its own folder on "+ "the machine) or declare a 'directory' param.",+ )+ else:+ directory = str(self.text(slot, directory_field, values, "directory"))++ # A room param is the server's to check, so it is not among the known+ # values; for a join it is the name the deployer gave.+ join_values = {**values, **self.room_inputs}+ join = []+ for j in interpolate(entry.get("join") or [], join_values):+ if not isinstance(j, str) or not j.strip():+ continue+ left = [n for n in PLACEHOLDER_RE.findall(j) if n in self.params]+ if left:+ self.problem(+ slot,+ "input_missing",+ f"it joins the room {', '.join(left)} names, which has no "+ "value; give it in inputs.",+ )+ continue+ join.append(j)++ addressing = str(entry.get("addressing") or "owner")+ if addressing not in _AGENT_ADDRESSING:+ self.problem(+ slot,+ "invalid_addressing",+ f"addressing '{addressing}' is not one of "+ f"{', '.join(_AGENT_ADDRESSING)}.",+ )++ instructions = str(+ self.text(slot, entry.get("instructions") or "", values, "instructions")+ )+ if not instructions.strip():+ self.problem(slot, "instructions_unsaid", "it has no instructions.")++ connections = self.connections(entry, slot, values)+ repo = entry.get("repo")+ if repo:+ repo_text = str(self.text(slot, repo, values, "repo"))+ instructions += repo_note(repo_text)++ isolation = str(interpolate(entry.get("isolation") or "shared", values))+ if isolation not in ("shared", "isolated"):+ self.problem(+ slot,+ "invalid_isolation",+ f"isolation '{isolation}' is not shared or isolated.",+ )+ auto_approve = interpolate(entry.get("auto_approve", False), values)+ if not isinstance(auto_approve, bool):+ self.problem(+ slot, "invalid_auto_approve", "auto_approve is not true or false."+ )+ advanced = self.text(+ slot, entry.get("advanced_config") or {}, values, "advanced_config"+ )+ if not isinstance(advanced, dict):+ self.problem(+ slot, "invalid_advanced_config", "advanced_config is not a mapping."+ )+ model = entry.get("model")+ model_text = (+ str(self.text(slot, model, values, "model")) if model is not None else ""+ )+ display_name = entry.get("display_name")++ if len(self.problems) > before:+ return None+ assert machine is not None and provider is not None+ return NewAgentPlan(+ slot=slot,+ name=name,+ description=str(+ interpolate(entry.get("description") or "", values) or name+ ),+ display_name=(+ str(interpolate(display_name, values)) if display_name else None+ ),+ instructions=instructions,+ provider=provider,+ machine=machine,+ model=model_text or None,+ advanced_config=dict(advanced),+ isolation=isolation,+ auto_approve=bool(auto_approve),+ directory=directory,+ addressing=addressing,+ connections=connections,+ joins=join,+ )++ def connections(+ self, entry: dict[str, Any], slot: str, values: dict[str, Any]+ ) -> list[ConnectionPlan]:+ raw = entry.get("connections") or []+ if not isinstance(raw, list):+ self.problem(slot, "invalid_connections", "connections is not a list.")+ return []+ plans: list[ConnectionPlan] = []+ for item in self.text(slot, raw, values, "connections"):+ if isinstance(item, str):+ item = {"service": item}+ if not isinstance(item, dict) or not item.get("service"):+ self.problem(+ slot,+ "invalid_connections",+ "each connection is a service name or {service, access, repos}.",+ )+ continue+ access = item.get("access")+ if access not in (None, "read", "write"):+ self.problem(+ slot,+ "invalid_connections",+ f"{item['service']}: access '{access}' is not read or write.",+ )+ continue+ repos = item.get("repos") or []+ if isinstance(repos, str):+ repos = [repos]+ plans.append(+ ConnectionPlan(+ service=str(item["service"]),+ access=access,+ repositories=[str(r) for r in repos if str(r).strip()],+ )+ )+ return plans+++def plan_template(+ text: str,+ filled: dict[str, str],+ inputs: dict[str, Any],+ *,+ builtins: dict[str, str],+ machines: list[dict[str, Any]] | None,+) -> TemplatePlan:+ """What running ``text`` on the server creates.++ ``filled`` puts an existing agent in a slot, by the name the template+ writes or the one it resolves to; only an entry that says+ ``allow_existing: true`` takes one. Every other entry is created as a+ managed agent. ``machines`` is the owner's machines as ``list_machines``+ reports them (None without agent management), for a ``machine`` or+ ``provider`` param's candidates. Refused with every problem found, before+ anything is created.+ """+ data = _load(text)+ room_addressing: dict[str, list[str]] = {}+ if is_v2(data):+ compiled = compile_v2(text, inputs, builtins)+ text, inputs, room_addressing = (+ compiled.document,+ compiled.inputs,+ compiled.room_addressing,+ )+ # A version 2 slot is filled by its resource's key.+ filled = {compiled.names.get(k, k): v for k, v in filled.items()}+ data = _load(text)+ values = {**builtins, **_known_values(data, inputs)}+ values.pop(AGENTS_DIR[1:-1], None)+ planner = _Planner(data, values, machines)+ planner.room_inputs = {+ name: str(value)+ for name, value in inputs.items()+ if planner.params.get(name, {}).get("type") == "room"+ and value not in (None, "")+ }+ known = set(filled)+ names: dict[str, str] = {}+ existing: dict[str, str] = {}+ new_agents: list[NewAgentPlan] = []+ for index, entry in enumerate(planner.entries):+ written = _written_name(entry)+ resolved = _resolved_name(entry, values)+ slot = resolved or written or f"agent {index + 1}"+ chosen = filled.get(written) or filled.get(resolved)+ known -= {written, resolved}+ if chosen:+ if entry.get("allow_existing") is not True:+ planner.problem(+ slot,+ "existing_not_allowed",+ "the template does not let an existing agent stand in for "+ "it (no allow_existing: true); it is created.",+ )+ continue+ existing[slot] = chosen+ for key in (written, resolved):+ if key:+ names[key] = chosen+ continue+ plan = planner.plan(entry, slot)+ if plan is not None:+ new_agents.append(plan)+ for key in (written, resolved):+ if key:+ names[key] = plan.name+ for unknown in sorted(known):+ planner.problem(+ unknown,+ "no_such_slot",+ "the template has no agent by that name. get_template lists its "+ "agent slots.",+ )+ if planner.problems:+ raise AgentsNotCreated(planner.problems)+ if _room_part(data) is None:+ return TemplatePlan(new_agents, existing, None, {}, room_addressing)+ document, run_inputs = room_document(text, names, inputs)+ return TemplatePlan(new_agents, existing, document, run_inputs, room_addressing)diff --git a/core/switch_core/bridges/agent/operations/agent_management.py b/core/switch_core/bridges/agent/operations/agent_management.pyindex 8534d94b2..ee4528132 100644--- a/core/switch_core/bridges/agent/operations/agent_management.py+++ b/core/switch_core/bridges/agent/operations/agent_management.py@@ -246,6 +246,7 @@ async def create_agent(instructions=instructions,directory=directory,auto_approve=auto_approve,+ isolation="shared",start=start,),get_protocol(),diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.pyindex 055c4c3fa..b8609b5c6 100644--- a/core/switch_core/bridges/agent/operations/definitions.py+++ b/core/switch_core/bridges/agent/operations/definitions.py@@ -12,13 +12,13 @@ and room come from `operations.context`.from __future__ import annotationsimport logging-from collections.abc import AsyncIterator+from collections.abc import AsyncIterator, Sequencefrom contextlib import asynccontextmanagerfrom typing import Anyfrom switch_core.agent_refusals import AgentRefused, record_refusalfrom switch_core.agent_template_ops import ActingFor, AgentTemplates-from switch_core.agent_templates import room_document+from switch_core.agent_templates import plan_templatefrom switch_core.bridges.agent.api.handlers import parse_timestamp_msfrom switch_core.bridges.agent.operations.agent_management import (management_permission,@@ -46,10 +46,23 @@ from switch_core.bridges.agent.protocol.agent_detail import AgentProfileUpdatefrom switch_core.bridges.agent.protocol.agent_management import ManagedAgentChangesfrom switch_core.bridges.agent.protocol.instructions import build_room_instructionsfrom switch_core.bridges.agent.protocol.types import IntegrationProfile-from switch_core.db.models import CollaborationBridge, User+from switch_core.db.models import CollaborationBridge, User, require_tenant_idfrom switch_core.db.stores.template_store import TemplateStore+from switch_core.feature_flags import AGENT_MANAGEMENTfrom switch_core.rooms_yaml import GroupSpec, template_json_schemafrom switch_core.template_guide import TEMPLATE_GUIDE+from switch_core.template_runs import (+ LISTEN_TIMEOUT_SECONDS,+ AgentsNotCreated,+ CheckedAgent,+ CreatedAgent,+ NewAgentPlan,+ Problem,+ TemplateAgents,+ pending_addressing,+ room_ids_of,+)+from switch_core.template_v2 import is_v2_textlogger = logging.getLogger(__name__)@@ -1702,7 +1715,8 @@ async def create_room_from_yaml(yaml: str,inputs: dict[str, Any] | None = None,) -> dict[str, Any]:- """Provision a room, or a group of rooms, from a YAML template.+ """Provision a room, or a group of rooms, from a YAML template; a+ ``version: 2`` document creates its agents too, as ``run_template`` does.The agent-side mirror of the gateway's ``POST /rooms/from-yaml``: thedocument is parsed, its ``params:`` resolved from ``inputs``, and the@@ -1733,7 +1747,11 @@ async def create_room_from_yaml(rooms: [...], errors: [...]}``."""async with _refusals_reported("create_room_from_yaml"):- return await _provision_as_agent(yaml, inputs)+ if is_v2_text(yaml):+ return await _run_document(yaml, inputs, {}, template_name=None)+ return await _provision_as_agent(+ yaml, inputs, template_name=None, new_agents=[], room_addressing={}+ )async def _acting_for() -> ActingFor:@@ -1775,14 +1793,22 @@ async def _refusals_reported(operation_name: str) -> AsyncIterator[None]:async def _provision_as_agent(- yaml: str,+ yaml: str | None,inputs: dict[str, Any] | None,*,- template_name: str | None = None,+ template_name: str | None,+ new_agents: Sequence[NewAgentPlan],+ room_addressing: dict[str, list[str]],) -> dict[str, Any]:- """Create the rooms a document describes, as the calling agent: the one- path for a document an agent writes and a template it runs, so the run- guards in ``agent_runs`` apply the same to both."""+ """Create the agents and rooms a document describes, as the calling+ agent: the one path for a document an agent writes and a template it+ runs, so the run guards in ``agent_runs`` apply the same to both.++ ``new_agents`` are created first, as managed agents of the owner, once+ every check of the agents and the rooms has passed; when the rooms then+ fail, they are deleted again. ``yaml`` is None for a template that+ creates agents and no room.+ """protocol = get_protocol()acting = await _acting_for()agent, owner = acting.agent, acting.owner@@ -1790,6 +1816,34 @@ async def _provision_as_agent(# document it writes or a template it runs attaches only what the owner# could attach as a member, never another person's private reference.+ tenant_id = require_tenant_id()+ creator: TemplateAgents | None = None+ checked: list[CheckedAgent] = []+ if new_agents:+ if management_port() is not None:+ permission = await management_permission()+ if isinstance(permission, str):+ raise AgentsNotCreated(+ [+ Problem(p.slot, "cannot_manage_agents", permission)+ for p in new_agents+ ]+ )+ creator = TemplateAgents(+ protocol=protocol,+ management=management_port(),+ broker=protocol.service_broker,+ listen_timeout=LISTEN_TIMEOUT_SECONDS,+ )+ checked = await creator.check(tenant_id, owner.id, new_agents)+ created_names = {plan.name for plan in new_agents}++ if yaml is None:+ if creator is None:+ raise ValueError("The template describes no agent and no room")+ created = await creator.create(tenant_id, owner.id, checked)+ return {"created_agents": _created_view(created)}+rooms_yaml = protocol.room_yaml_service()inputs = await rooms_yaml.resolve_defaults(yaml, inputs)builtins = await rooms_yaml.builtins_for(@@ -1797,12 +1851,15 @@ async def _provision_as_agent()parsed = rooms_yaml.parse_template(yaml, inputs=inputs, builtins=builtins)await rooms_yaml.check_entity_params(parsed)+ await rooms_yaml.check_bridges(parsed)room_specs = ([(r, r.kickoff) for r in parsed.spec.rooms]if isinstance(parsed.spec, GroupSpec)else [(parsed.spec, parsed.kickoff)])- await _require_agents_exist([n for spec, _ in room_specs for n in spec.agents])+ await _require_agents_exist(+ [n for spec, _ in room_specs for n in spec.agents if n not in created_names]+ )kickoffs = [(text, list(spec.agents), dict(spec.aliases or {}))for spec, text in room_specs@@ -1813,27 +1870,61 @@ async def _provision_as_agent(owner_name=owner.name,from_room_id=await connected_room(),kickoffs=kickoffs,+ pending=pending_addressing(new_agents, owner.id, room_addressing),) as origin:- if isinstance(parsed.spec, GroupSpec):- group_result = await rooms_yaml.provision_group(- parsed.spec,- user_id=owner.id,- is_admin=False,- creator_name=builtins["$creator"],- origin=origin,- template_name=template_name,- )- return group_result.model_dump()- result = await rooms_yaml.provision(- parsed.spec,- kickoff=parsed.kickoff,- user_id=owner.id,- is_admin=False,- creator_name=builtins["$creator"],- origin=origin,- template_name=template_name,+ created = (+ []+ if creator is None+ else await creator.create(tenant_id, owner.id, checked))- return result.model_dump()+ try:+ if isinstance(parsed.spec, GroupSpec):+ group_result = await rooms_yaml.provision_group(+ parsed.spec,+ user_id=owner.id,+ is_admin=False,+ creator_name=builtins["$creator"],+ origin=origin,+ template_name=template_name,+ )+ result = group_result.model_dump()+ else:+ room_result = await rooms_yaml.provision(+ parsed.spec,+ kickoff=parsed.kickoff,+ user_id=owner.id,+ is_admin=False,+ creator_name=builtins["$creator"],+ origin=origin,+ template_name=template_name,+ )+ result = room_result.model_dump()+ if creator is not None and room_addressing:+ await creator.open_to_rooms(+ tenant_id, created, room_addressing, room_ids_of(result)+ )+ except Exception as error:+ if creator is None or not created:+ raise+ raise await creator.undone(+ created, f"the rooms could not be created: {error}"+ ) from error+ if new_agents:+ result["created_agents"] = _created_view(created)+ return result+++def _created_view(created: Sequence[CreatedAgent]) -> list[dict[str, Any]]:+ return [+ {+ "slot": agent.slot,+ "agent_id": agent.agent_id,+ "name": agent.name,+ "machine": agent.machine,+ "listening": agent.listening,+ }+ for agent in created+ ]async def _require_agents_exist(names: list[str]) -> None:@@ -1856,7 +1947,11 @@ async def _require_agents_exist(names: list[str]) -> None:def _agent_templates() -> AgentTemplates:protocol = get_protocol()- return AgentTemplates(TemplateStore(), max_bytes=protocol.config.template_max_bytes)+ return AgentTemplates(+ TemplateStore(),+ max_bytes=protocol.config.template_max_bytes,+ agent_management=protocol.config.feature_flags[AGENT_MANAGEMENT],+ )@operation@@ -1911,16 +2006,26 @@ async def get_template(template_id: str) -> dict[str, Any]:Use it before ``run_template`` to know what to fill in. ``params`` arethe inputs (``required`` is as the template writes it; a param with nodefault usually needs a value). ``agent_slots`` lists the agents an agent- or team template would create: the server cannot create agents, so to run- one you fill each slot with an existing agent.+ or team template would create, as managed agents of your owner: each+ slot's ``machine`` (or a ``machine`` param) says where it runs, and+ ``provider``, ``model``, ``directory`` and ``connections`` what it is.+ A slot with only a ``location`` (this computer or an SSH host) runs on+ the machine of that name, or else the first online machine of your+ owner's that can run it. ``allow_existing`` says whether an+ existing agent may stand in for it instead (``run_template``'s+ ``agents``).Args:template_id: The id from ``list_templates``.Returns:``{id, name, description, kind, visibility, saved_by, can_edit,- params: [{name, type, description, default, required}],- agent_slots: [{name, description}], content}``.+ params: [{name, type, description, default, required, if}],+ agent_slots: [{name, description, allow_existing, provider, machine,+ location, model, directory, connections: [{service, access,+ repos}]}], content}``. Slot fields are as the template writes them,+ ``{param}`` placeholders included (a setting a param says for every+ agent shows as that ``{param}``); null where it says nothing."""protocol = get_protocol()async with _refusals_reported("get_template"):@@ -1935,25 +2040,41 @@ async def run_template(inputs: dict[str, Any] | None = None,agents: dict[str, str] | None = None,) -> dict[str, Any]:- """Create the rooms a saved template describes, as you, the same way- ``create_room_from_yaml`` does with a document you write.+ """Create the agents and rooms a saved template describes, as you, the+ same way ``create_room_from_yaml`` does with a document you write.Everything ``create_room_from_yaml`` says about kickoffs and refusalsapplies here too, and the run is listed under the template's name in- Switch Console. An agent or team template runs only when each agent it- would create is filled with an agent that already exists: creating agents- happens in Switch Console.+ Switch Console.++ An agent or team template creates its agents as managed agents of your+ owner, each on the machine its entry names (``machine:`` or a ``machine``+ param), before the rooms. That needs agent management on this server and+ the "can manage agents" capability, and each machine online with the+ provider installed and logged in. Everything is checked first: when+ anything would fail, nothing is created and the refusal lists every+ problem with its reason code. If the rooms then fail, the agents created+ are deleted again. Confirm what will be created with the person asking+ first: it starts real agents on their machines.Args:template_id: The id from ``list_templates``.- inputs: Values for the template's params (see ``get_template``).- agents: For an agent or team template, which existing agent fills- each slot: ``{slot name: agent name}``, the slot named as- ``get_template`` lists it or as it reads with your inputs.+ inputs: Values for the template's params (see ``get_template``),+ including a ``machine`` or ``provider`` param.+ agents: Existing agents to stand in for slots instead of creating+ them, ``{slot name: agent name}``, the slot named as+ ``get_template`` lists it or as it reads with your inputs. Only a+ slot whose entry says ``allow_existing: true`` takes one.Returns:As ``create_room_from_yaml``: for a room ``{room_id, room_name, ...}``,- for a group ``{group_id, group_name, rooms, errors}``.+ for a group ``{group_id, group_name, rooms, errors}``; plus, when it+ created agents, ``created_agents``: each ``{slot, agent_id, name,+ machine, listening}``, ``listening`` false when the agent was not+ taking events before its rooms were made, so the kickoff may not have+ reached it. Check them with ``list_managed_agents`` as after+ ``create_agent``. A template with no room returns only+ ``created_agents``."""protocol = get_protocol()async with _refusals_reported("run_template"):@@ -1961,10 +2082,59 @@ async def run_template(async with protocol.session_factory() as session:template = await _agent_templates().load(session, acting, template_id)content, name = template.content, template.name- document, run_inputs = room_document(content, agents or {}, inputs or {})- return await _provision_as_agent(- document, run_inputs or None, template_name=name- )+ return await _run_document(content, inputs, agents or {}, template_name=name)+++async def _run_document(+ content: str,+ inputs: dict[str, Any] | None,+ filled: dict[str, str],+ *,+ template_name: str | None,+) -> dict[str, Any]:+ """Work a template's agents and rooms out of its document and create+ them, as the calling agent."""+ protocol = get_protocol()+ acting = await _acting_for()+ rooms_yaml = protocol.room_yaml_service()+ if is_v2_text(content):+ # A version 2 condition may read a messaging app or room param+ # whose value is the first candidate the server has.+ inputs = await rooms_yaml.resolve_defaults(content, inputs)+ builtins = await rooms_yaml.builtins_for(+ user_id=acting.owner.id,+ name=acting.owner.name,+ email=acting.owner.email,+ text=content,+ inputs=inputs,+ )+ plan = plan_template(+ content,+ filled,+ inputs or {},+ builtins=builtins,+ machines=await _owners_machines(),+ )+ return await _provision_as_agent(+ plan.document,+ plan.inputs or None,+ template_name=template_name,+ new_agents=plan.new_agents,+ room_addressing=plan.room_addressing,+ )+++async def _owners_machines() -> list[dict[str, Any]] | None:+ """The owner's machines, for a template's machine and provider choices;+ None when this agent cannot see them (no agent management, or no+ capability), which the run's checks then report."""+ port = management_port()+ if port is None:+ return None+ permission = await management_permission()+ if isinstance(permission, str):+ return None+ return await port.list_machines(permission.tenant_id, permission.owner.id)@operation@@ -1973,6 +2143,7 @@ async def save_template(description: str,yaml: str,visibility: str = "private",+ bypass_warnings: bool = False,) -> dict[str, Any]:"""Save a template to this workspace, so it can be found and run again.@@ -1986,21 +2157,28 @@ async def save_template(yaml: The template document, as ``create_room_from_yaml`` takes it.visibility: ``private`` (only your owner sees it) or ``shared``(everyone on the workspace sees it, only you change it).+ bypass_warnings: Leave false. A document with warnings, such as an+ agent it never says which provider runs, is then refused and the+ warnings listed, so you can fix them or advise whoever asked+ first. Set true only to save it anyway: Switch Console will not+ create an agent from it until what a warning names is fixed.Returns:- ``{id, name, kind, visibility}``.+ ``{id, name, kind, visibility, warnings}``. ``warnings`` lists what+ was saved past with ``bypass_warnings``; empty otherwise."""protocol = get_protocol()async with _refusals_reported("save_template"):acting = await _acting_for()async with protocol.session_factory() as session:- template = await _agent_templates().save(+ template, warnings = await _agent_templates().save(session,acting,name=name,description=description,content=yaml,visibility=visibility,+ bypass_warnings=bypass_warnings,)await session.commit()return {@@ -2008,6 +2186,7 @@ async def save_template("name": template.name,"kind": template.kind,"visibility": visibility,+ "warnings": warnings,}@@ -2018,20 +2197,25 @@ async def update_template(description: str | None = None,yaml: str | None = None,visibility: str | None = None,+ bypass_warnings: bool = False,) -> dict[str, Any]:"""Change a template you saved. Only the fields you pass change.Templates saved by a person, or by another agent, cannot be changed byyou; save your own version under another name instead.+ A new ``yaml`` with warnings is refused unless ``bypass_warnings`` is+ true, as in ``save_template``.+Returns:- ``{id, name, kind, visibility, version}``.+ ``{id, name, kind, visibility, version, warnings}``. ``warnings``+ lists what was saved past with ``bypass_warnings``; empty otherwise."""protocol = get_protocol()async with _refusals_reported("update_template"):acting = await _acting_for()async with protocol.session_factory() as session:- template = await _agent_templates().update(+ template, warnings = await _agent_templates().update(session,acting,template_id,@@ -2039,6 +2223,7 @@ async def update_template(description=description,content=yaml,visibility=visibility,+ bypass_warnings=bypass_warnings,)await session.commit()return {@@ -2049,6 +2234,7 @@ async def update_template(if template.read_visibility == "public"else "private","version": template.version,+ "warnings": warnings,}diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.pyindex bca651c05..1fe21ed8e 100644--- a/core/switch_core/bridges/agent/protocol/agent_core.py+++ b/core/switch_core/bridges/agent/protocol/agent_core.py@@ -142,6 +142,7 @@ if TYPE_CHECKING:from switch_core.clients.actor import Actorfrom switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfig+ from switch_core.connections.broker import ServiceBrokerfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore@@ -162,6 +163,7 @@ logger = logging.getLogger(__name__)# \A and \Z rather than ^ and $: Python's $ also matches before a single# trailing newline, which would let an identifier carry a line break._VALID_NAME_RE = re.compile(r"\A[a-z0-9][a-z0-9._-]*\Z")+VALID_AGENT_NAME_RE = _VALID_NAME_RE# A hard ceiling on one read_context call, whatever limit the caller asks for.# History comes from a single indexed query now, so the only thing this guards@@ -284,6 +286,9 @@ class AgentCore:# still exists. Set by the process wiring when something outside Core keeps# state about agents that a cascade alone would drop without telling anyone._agent_removal_listener: Callable[[str, str], Awaitable[None]] | None = None+ # The credential broker, set by the process wiring when service+ # connections are on; None means they are off, and nothing can be granted.+ service_broker: ServiceBroker | None = Nonedef __init__(self,diff --git a/core/switch_core/bridges/agent/protocol/agent_management.py b/core/switch_core/bridges/agent/protocol/agent_management.pyindex 4f8dc8dcd..0478c1392 100644--- a/core/switch_core/bridges/agent/protocol/agent_management.py+++ b/core/switch_core/bridges/agent/protocol/agent_management.py@@ -51,9 +51,21 @@ class NewManagedAgent:instructions: strdirectory: str | Noneauto_approve: bool+ isolation: strstart: bool+@dataclass(frozen=True)+class CheckedPlacement:+ """Where a new managed agent would go, once management has checked that+ the machine can take it. `workspaces_dir` is where the machine keeps+ agents' workspaces, None when it has not reported one."""++ machine_id: str+ machine_name: str+ workspaces_dir: str | None++@dataclass(frozen=True)class ManagedAgentChanges:"""What an agent asks to change in a managed agent's definition and@@ -119,6 +131,15 @@ class AgentManagementPort(Protocol):"""Create and place a managed agent owned by `owner_id`."""...+ async def check_new_agent(+ self, tenant_id: str, owner_id: str, spec: NewManagedAgent+ ) -> CheckedPlacement:+ """Every check `create_agent` makes before it registers anything (the+ machine is the owner's and can run the provider now, the definition+ validates), without creating anything. Refused as `create_agent` would+ be."""+ ...+async def list_managed_agents(self, tenant_id: str, owner_id: str) -> list[dict[str, Any]]:diff --git a/core/switch_core/clients/actor.py b/core/switch_core/clients/actor.pyindex 1e8e94f63..fb239c6e5 100644--- a/core/switch_core/clients/actor.py+++ b/core/switch_core/clients/actor.py@@ -125,6 +125,18 @@ class Actor[ConfigT: ClientConfig]:async def wait_ready(self) -> None:await self._ready.wait()+ async def wait_receiving(self, timeout: float) -> bool:+ """Block until this actor's client is taking events, so a room it is+ added to from now on is one it reads from the start, up to `timeout`+ seconds. False on timeout."""+ loop = asyncio.get_running_loop()+ deadline = loop.time() + timeout+ try:+ await asyncio.wait_for(self._ready.wait(), timeout)+ except TimeoutError:+ return False+ return await self._transport.wait_receiving(max(0.0, deadline - loop.time()))+async def set_display_name(self, display_name: str) -> None:"""Change the name this actor shows under.diff --git a/core/switch_core/connections/adapters/github.py b/core/switch_core/connections/adapters/github.pyindex b38d7e46b..c7b237867 100644--- a/core/switch_core/connections/adapters/github.py+++ b/core/switch_core/connections/adapters/github.py@@ -131,6 +131,44 @@ class GitHubAdapter:raise _vendor_error(error) from Nonereturn ConnectionSecret({**secret.values, **refreshed})+ async def resolve_repositories(+ self, access_token: str, names: list[str]+ ) -> dict[str, Any]:+ """A grant's resources for repositories named `owner/name`: the one+ installation of the App that reaches them all, and their ids."""+ try:+ reach = await self._connections.repositories(access_token)+ except GitHubError as error:+ raise _vendor_error(error) from None+ wanted = {name.lower(): name for name in names}+ for installation in reach.installations:+ found = {+ repo["name"].lower(): repo["id"]+ for repo in installation["repositories"]+ if repo["name"].lower() in wanted+ }+ if len(found) == len(wanted):+ return {+ "installation_id": installation["id"],+ "repository_ids": sorted(found.values()),+ }+ reached = {+ repo["name"].lower()+ for installation in reach.installations+ for repo in installation["repositories"]+ }+ unseen = sorted(name for key, name in wanted.items() if key not in reached)+ if unseen:+ raise ServiceAdapterError(+ "Your GitHub account does not reach "+ f"{', '.join(unseen)} through the GitHub App. Install the App on "+ "it, or check the name is owner/name."+ )+ raise ServiceAdapterError(+ "One GitHub grant reaches repositories of one installation of the "+ f"GitHub App, and {', '.join(names)} span several."+ )+async def check_grant(self, access_token: str, request: IssueRequest) -> dict[str, Any]:diff --git a/core/switch_core/connections/broker.py b/core/switch_core/connections/broker.pyindex ad139ea89..504eb6a61 100644--- a/core/switch_core/connections/broker.py+++ b/core/switch_core/connections/broker.py@@ -282,6 +282,28 @@ def _require_owners_controller(principal: Principal, owner_id: str | None) -> No)+@dataclass(frozen=True)+class _GrantTerms:+ name: str+ adapter: ServiceAdapter+ access: AccessLevel+ reach: dict[str, Any]+ tool_mode: Literal["allow", "deny"]+ tools: list[str]+ passes_through: bool+++@dataclass(frozen=True)+class CheckedGrant:+ """A grant `check_grant_terms` found the owner can make: what to pass+ `set_grant` once the agent exists. `access` is None for a service whose+ grant is on or off."""++ service: str+ access: AccessLevel | None+ resources: dict[str, Any]++def get_service_broker(request: Request) -> ServiceBroker:"""The broker `main` installs on the agent bridge and the gateway."""broker = getattr(request.app.state, "service_broker", None)@@ -1031,29 +1053,19 @@ class ServiceBroker:verb = "read and write" if access == "write" else "read"return f"{agent_name} can {verb} {self._entry(grant.service).definition.name}."- async def set_grant(+ async def _grant_terms(self,session: AsyncSession,*,- agent: Agent,- actor_id: str,+ owner_id: str,service: str,access: AccessLevel | None,tool_mode: Literal["allow", "deny"] | None,tools: list[str] | None,- resources: dict[str, Any],- ) -> tuple[ServiceGrant, str | None]:- """Create or replace the agent's grant on its owner's own connection.-- A new grant with no `access` reads, with the level's tools. A- pass-through service's grant is on or off: it names no level or tools,- and takes the connection's. Commits `session`. Replacing a grant with- one that reaches less, or on a different account, revokes what was- issued under the old one, and the warning says when some of it could- not be revoked yet.- """- if agent.owner_id != actor_id:- raise ServiceError(404, NOT_FOUND, "Agent not found.", retryable=False)+ ) -> _GrantTerms:+ """What a grant on the owner's connection to `service` would be, or+ the refusal: the service is set up here, the owner is connected to it+ and allows the level, and the tools are the level's."""if service not in self._catalog:raise ServiceError(404, NOT_FOUND, f"No service named {service!r}.", retryable=False@@ -1064,7 +1076,7 @@ class ServiceBroker:entry = self._entry(service)name = entry.definition.nameadapter = self._adapter(service)- connection = await self._store.get_connection(session, actor_id, service)+ connection = await self._store.get_connection(session, owner_id, service)if connection is None:raise ServiceError(409,@@ -1121,6 +1133,116 @@ class ServiceBroker:f"Not {level_name} tools of {name}: {', '.join(unknown)}.",retryable=False,)+ return _GrantTerms(+ name=name,+ adapter=adapter,+ access=level_name,+ reach=reach,+ tool_mode=mode,+ tools=chosen,+ passes_through=_passes_through(entry),+ )++ async def check_grant_terms(+ self,+ session: AsyncSession,+ *,+ owner_id: str,+ service: str,+ access: AccessLevel | None,+ repositories: list[str],+ ) -> CheckedGrant:+ """Whether an agent of the owner's could be granted `service`, checked+ as `set_grant` would and with the vendor, without granting anything.++ `repositories` names what a GitHub grant reaches (`owner/name`); the+ result carries them as the grant's resources. Ends `session`'s+ transaction.+ """+ terms = await self._grant_terms(+ session,+ owner_id=owner_id,+ service=service,+ access=access,+ tool_mode=None,+ tools=None,+ )+ await session.commit()+ owner_token = await self._access_token(owner_id, service, terms.adapter)+ resources: dict[str, Any] = {}+ try:+ if repositories:+ resolve = getattr(terms.adapter, "resolve_repositories", None)+ if resolve is None:+ raise ServiceError(+ 422,+ VALIDATION_ERROR,+ f"{terms.name} has no repositories to choose from; "+ "leave out repos.",+ retryable=False,+ )+ resources = await resolve(owner_token.token, repositories)+ checked = await terms.adapter.check_grant(+ owner_token.token,+ IssueRequest(+ service=service,+ access=terms.access,+ reach=terms.reach,+ resources=resources,+ ),+ )+ except ReauthorizationRequiredError as error:+ raise await self._needs_reauthorization(owner_id, service, error) from None+ except ServiceUnavailableError as error:+ raise ServiceError(503, INTERNAL, str(error), retryable=True) from None+ except ServiceAdapterError as error:+ raise ServiceError(+ 422, VALIDATION_ERROR, str(error), retryable=False+ ) from None+ return CheckedGrant(+ service=service,+ access=None if terms.passes_through else terms.access,+ resources=checked,+ )++ async def set_grant(+ self,+ session: AsyncSession,+ *,+ agent: Agent,+ actor_id: str,+ service: str,+ access: AccessLevel | None,+ tool_mode: Literal["allow", "deny"] | None,+ tools: list[str] | None,+ resources: dict[str, Any],+ ) -> tuple[ServiceGrant, str | None]:+ """Create or replace the agent's grant on its owner's own connection.++ A new grant with no `access` reads, with the level's tools. A+ pass-through service's grant is on or off: it names no level or tools,+ and takes the connection's. Commits `session`. Replacing a grant with+ one that reaches less, or on a different account, revokes what was+ issued under the old one, and the warning says when some of it could+ not be revoked yet.+ """+ if agent.owner_id != actor_id:+ raise ServiceError(404, NOT_FOUND, "Agent not found.", retryable=False)+ terms = await self._grant_terms(+ session,+ owner_id=actor_id,+ service=service,+ access=access,+ tool_mode=tool_mode,+ tools=tools,+ )+ name, adapter = terms.name, terms.adapter+ level_name, reach, mode, chosen = (+ terms.access,+ terms.reach,+ terms.tool_mode,+ terms.tools,+ )await session.commit()owner_token = await self._access_token(actor_id, service, adapter)diff --git a/core/switch_core/gateway/rooms.py b/core/switch_core/gateway/rooms.pyindex 0016058e7..0bbf9a3d0 100644--- a/core/switch_core/gateway/rooms.py+++ b/core/switch_core/gateway/rooms.py@@ -2,18 +2,22 @@ from __future__ import annotationsimport jsonimport logging-from typing import Annotated, cast+from typing import Annotated, Any, Literal, castfrom fastapi import APIRouter, Depends, HTTPException, Query, Request, Response+from fastapi.responses import JSONResponse+from pydantic import BaseModel, ConfigDict, Fieldfrom sqlalchemy.ext.asyncio import AsyncSession+from switch_core.agent_templates import plan_templatefrom switch_core.authz import Action, Principal, can, require, require_manage+from switch_core.bridges.agent.operations.agent_management import management_portfrom switch_core.bridges.agent.protocol.agent_core import AgentCorefrom switch_core.bridges.collaboration.models import (BridgeOperationError,ChannelType,)-from switch_core.db.models import Room, RoomGroup, User+from switch_core.db.models import Room, RoomGroup, User, require_tenant_idfrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_group_store import RoomGroupStore@@ -61,6 +65,16 @@ from switch_core.rooms_yaml import (template_json_schema,)from switch_core.telemetry import emit_safely+from switch_core.template_runs import (+ LISTEN_TIMEOUT_SECONDS,+ AgentsNotCreated,+ ConnectionPlan,+ NewAgentPlan,+ RunUndone,+ TemplateAgents,+ room_ids_of,+)+from switch_core.template_v2 import is_v2_textlogger = logging.getLogger(__name__)@@ -472,6 +486,270 @@ async def create_room_from_yaml(raise HTTPException(status_code=502, detail=str(e)) from e+class TemplateConnectionBody(BaseModel):+ model_config = ConfigDict(extra="forbid")+ service: str+ access: Literal["read", "write"] | None = None+ repos: list[str] = Field(default_factory=list)+++class TemplateAgentBody(BaseModel):+ """One agent a template run creates, resolved by the client."""++ model_config = ConfigDict(extra="forbid")+ slot: str+ name: str+ description: str+ display_name: str | None+ instructions: str+ provider: str+ machine: str+ model: str | None+ advanced_config: dict[str, Any]+ isolation: Literal["shared", "isolated"]+ auto_approve: bool+ directory: str | None+ addressing: Literal["owner", "owner-agents", "anyone"]+ connections: list[TemplateConnectionBody]++ def plan(self) -> NewAgentPlan:+ return NewAgentPlan(+ slot=self.slot,+ name=self.name,+ description=self.description,+ display_name=self.display_name,+ instructions=self.instructions,+ provider=self.provider,+ machine=self.machine,+ model=self.model,+ advanced_config=self.advanced_config,+ isolation=self.isolation,+ auto_approve=self.auto_approve,+ directory=self.directory,+ addressing=self.addressing,+ connections=[+ ConnectionPlan(c.service, c.access, list(c.repos))+ for c in self.connections+ ],+ )+++class TemplateRunBody(BaseModel):+ """A template run: the agents it creates, then the room half (``yaml``,+ naming them by name; null for a template with no room)."""++ model_config = ConfigDict(extra="forbid")+ agents: list[TemplateAgentBody]+ yaml: str | None+ inputs: dict[str, Any] | None = None+ template_name: str+++def _refused_run(error: AgentsNotCreated | RunUndone) -> JSONResponse:+ content: dict[str, Any] = {"detail": str(error), "code": error.reason}+ if isinstance(error, AgentsNotCreated):+ content["problems"] = [p.as_dict() for p in error.problems]+ else:+ content["left_behind"] = error.left_behind+ return JSONResponse(status_code=409, content=content)++[email protected]("/from-template", status_code=201, response_model=None)+async def run_template_with_agents(+ body: TemplateRunBody,+ rooms_yaml: Annotated[RoomYamlService, Depends(get_room_yaml_service)],+ protocol: Annotated[AgentCore, Depends(get_protocol)],+ user: Annotated[User, Depends(get_current_user)],+ is_admin: Annotated[bool, Depends(get_tenant_is_admin)],+) -> dict[str, Any] | JSONResponse:+ """Run a template that creates agents: the agents first, as managed+ agents of the caller on their own machines, then its rooms.++ Everything is checked before anything is created: each machine can take+ its agent now, each name is free, each connection is the caller's to+ grant, and the room half parses. A refusal is 409 with ``code``+ ``agents_not_created`` and ``problems``, each ``{slot, code, message}``.+ When the rooms fail after the agents were created, the agents are deleted+ again: 409 with ``code`` ``run_undone`` and ``left_behind`` naming any+ that could not be. A room half that is wrong is 400, as from-yaml.++ Returns ``{created_agents: [{slot, agent_id, name, machine, listening}],+ room}``, ``room`` being what from-yaml returns, or null with no room+ half. ``listening`` is false for an agent that was not taking events+ before the rooms were made: the kickoff may not have reached it.+ """+ return await _run_as_person(+ rooms_yaml,+ protocol,+ user,+ is_admin,+ plans=[agent.plan() for agent in body.agents],+ document=body.yaml,+ inputs=body.inputs,+ template_name=body.template_name,+ room_addressing={},+ )+++class TemplateDocumentRunBody(BaseModel):+ """A whole template run from its document: the server works out the+ agents and rooms from the document and the inputs."""++ model_config = ConfigDict(extra="forbid")+ template: str+ inputs: dict[str, Any] | None = None+ # Existing agents standing in for slots that allow it: {slot: agent name}.+ filled: dict[str, str] = Field(default_factory=dict)+ template_name: str++[email protected]("/from-template-document", status_code=201, response_model=None)+async def run_template_document(+ body: TemplateDocumentRunBody,+ rooms_yaml: Annotated[RoomYamlService, Depends(get_room_yaml_service)],+ protocol: Annotated[AgentCore, Depends(get_protocol)],+ user: Annotated[User, Depends(get_current_user)],+ is_admin: Annotated[bool, Depends(get_tenant_is_admin)],+) -> dict[str, Any] | JSONResponse:+ """Run a template from its document, the way ``run_template`` does for an+ agent: the server resolves the agents (their machine and provider among+ the caller's machines), checks everything, creates the agents, then the+ rooms. For a ``version: 2`` document, whose conditions and references+ only the server resolves. Answers as ``from-template``.+ """+ inputs = body.inputs or {}+ try:+ if is_v2_text(body.template):+ inputs = await rooms_yaml.resolve_defaults(body.template, inputs) or {}+ builtins = await rooms_yaml.builtins_for(+ user_id=user.id,+ name=user.name,+ email=user.email,+ text=body.template,+ inputs=inputs,+ )+ port = management_port()+ machines = (+ await port.list_machines(require_tenant_id(), user.id)+ if port is not None+ else None+ )+ plan = plan_template(+ body.template, body.filled, inputs, builtins=builtins, machines=machines+ )+ except AgentsNotCreated as error:+ return _refused_run(error)+ except ValueError as e:+ raise HTTPException(status_code=400, detail=str(e)) from e+ return await _run_as_person(+ rooms_yaml,+ protocol,+ user,+ is_admin,+ plans=plan.new_agents,+ document=plan.document,+ inputs=plan.inputs or None,+ template_name=body.template_name,+ room_addressing=plan.room_addressing,+ )+++async def _run_as_person(+ rooms_yaml: RoomYamlService,+ protocol: AgentCore,+ user: User,+ is_admin: bool,+ *,+ plans: list[NewAgentPlan],+ document: str | None,+ inputs: dict[str, Any] | None,+ template_name: str,+ room_addressing: dict[str, list[str]],+) -> dict[str, Any] | JSONResponse:+ """Check everything, create the agents, then the rooms, as `user`; undo+ the agents when the rooms fail."""+ tenant_id = require_tenant_id()+ creator = TemplateAgents(+ protocol=protocol,+ management=management_port(),+ broker=protocol.service_broker,+ listen_timeout=LISTEN_TIMEOUT_SECONDS,+ )+ try:+ parsed = None+ builtins: dict[str, str] = {}+ if document is not None:+ inputs = await rooms_yaml.resolve_defaults(document, inputs)+ builtins = await rooms_yaml.builtins_for(+ user_id=user.id,+ name=user.name,+ email=user.email,+ text=document,+ inputs=inputs,+ )+ parsed = rooms_yaml.parse_template(+ document, inputs=inputs, builtins=builtins+ )+ await rooms_yaml.check_entity_params(parsed)+ await rooms_yaml.check_bridges(parsed)+ checked = await creator.check(tenant_id, user.id, plans)+ created = await creator.create(tenant_id, user.id, checked)+ room: ProvisionResult | GroupProvisionResult | None = None+ if parsed is not None:+ try:+ if isinstance(parsed.spec, GroupSpec):+ room = await rooms_yaml.provision_group(+ parsed.spec,+ user_id=user.id,+ is_admin=is_admin,+ creator_name=builtins["$creator"],+ template_name=template_name,+ )+ else:+ room = await rooms_yaml.provision(+ parsed.spec,+ kickoff=parsed.kickoff,+ user_id=user.id,+ is_admin=is_admin,+ creator_name=builtins["$creator"],+ template_name=template_name,+ )+ if room_addressing:+ await creator.open_to_rooms(+ tenant_id,+ created,+ room_addressing,+ room_ids_of(room.model_dump()),+ )+ except Exception as error:+ if not created:+ raise+ raise await creator.undone(+ created, f"the rooms could not be created: {error}"+ ) from error+ except (AgentsNotCreated, RunUndone) as error:+ return _refused_run(error)+ except ValueError as e:+ raise HTTPException(status_code=400, detail=str(e)) from e+ except PermissionError as e:+ raise HTTPException(status_code=403, detail=str(e)) from e+ except BridgeOperationError as e:+ raise HTTPException(status_code=502, detail=str(e)) from e+ return {+ "created_agents": [+ {+ "slot": agent.slot,+ "agent_id": agent.agent_id,+ "name": agent.name,+ "machine": agent.machine,+ "listening": agent.listening,+ }+ for agent in created+ ],+ "room": None if room is None else room.model_dump(),+ }++@router.get("/template-schema")async def get_template_schema(_user: Annotated[User, Depends(get_current_user)],diff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.pyindex 4d574f752..357b60282 100644--- a/core/switch_core/gateway/schemas.py+++ b/core/switch_core/gateway/schemas.py@@ -1384,13 +1384,17 @@ class TemplateSummary(BaseModel):"""id: str- owner_id: str+ # None for an official template, which comes with Switch.+ owner_id: str | Noneowner_name: str | None = Nonename: strdescription: strkind: strread_visibility: strwrite_visibility: str+ # Comes with Switch: served by the server on every workspace, and changed+ # by nobody (see `official_templates`).+ official: bool = False# What the caller may do with it, so a client shows Edit and Remove only# where the server would say yes. Admin here means the tenant's, which a# client cannot tell from the user's global role.diff --git a/core/switch_core/gateway/templates.py b/core/switch_core/gateway/templates.pyindex 6baa5ca93..391f6ac6e 100644--- a/core/switch_core/gateway/templates.py+++ b/core/switch_core/gateway/templates.py@@ -37,6 +37,7 @@ from switch_core.db.stores.template_store import (TemplateStore,)from switch_core.db.stores.user_store import UserStore+from switch_core.feature_flags import AGENT_MANAGEMENTfrom switch_core.gateway.auth import get_current_user, get_tenant_is_adminfrom switch_core.gateway.dependencies import (current_telemetry,@@ -55,6 +56,13 @@ from switch_core.gateway.schemas import (TemplateValidateRequest,TemplateValidateResponse,)+from switch_core.official_templates import (+ OfficialTemplate,+ is_official,+ matches,+ official_template,+ official_templates,+)from switch_core.telemetry import emit_safelyfrom switch_core.telemetry.ages import age_daysfrom switch_core.template_lint import lint_template@@ -116,6 +124,53 @@ def _summary()+def _official_detail(template: OfficialTemplate) -> TemplateDetail:+ return TemplateDetail(+ id=template.id,+ owner_id=None,+ owner_name="Switch",+ name=template.name,+ description=template.description,+ kind=template.kind,+ read_visibility=template.read_visibility,+ write_visibility=template.write_visibility,+ official=True,+ can_edit=False,+ can_manage=False,+ version=template.version,+ size_bytes=_size_bytes(template.content),+ created_at="",+ updated_at="",+ content=template.content,+ )+++def _official_or_none(+ template_id: str, config: SwitchConfig+) -> OfficialTemplate | None:+ """The official template an ``official:`` id names, or a 404 for one+ this release does not ship; None for any other id."""+ if not is_official(template_id):+ return None+ template = official_template(template_id, config.feature_flags[AGENT_MANAGEMENT])+ if template is None:+ raise HTTPException(+ status_code=404, detail=f"Template not found: {template_id}"+ )+ return template+++def _refuse_official(template_id: str) -> None:+ if is_official(template_id):+ raise HTTPException(+ status_code=403,+ detail=(+ "This template comes with Switch, so nobody can change or delete it. "+ "Save your own copy under another name to change it."+ ),+ )++def _detail(template: Template, owner_name: str | None, principal: Principal) -> TemplateDetail:@@ -234,6 +289,7 @@ async def list_templates(user_store: Annotated[UserStore, Depends(get_user_store)],user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],+ config: Annotated[SwitchConfig, Depends(get_config)],q: Annotated[str | None, Query()] = None,kind: Annotated[str | None, Query()] = None,owner_id: Annotated[str | None, Query()] = None,@@ -249,7 +305,17 @@ async def list_templates()names = await _owner_names(session, user_store, {r.owner_id for r in rows})principal = Principal(user.id, is_admin)- return [_summary(r, names.get(r.owner_id), principal) for r in rows]+ # The ones that come with Switch first, as nobody's own.+ official = (+ []+ if owner_id+ else [+ TemplateSummary(**_official_detail(t).model_dump(exclude={"content"}))+ for t in official_templates(config.feature_flags[AGENT_MANAGEMENT])+ if matches(t, q, kind)+ ]+ )+ return official + [_summary(r, names.get(r.owner_id), principal) for r in rows]@router.post("/templates", status_code=201)@@ -341,7 +407,11 @@ async def get_template(user_store: Annotated[UserStore, Depends(get_user_store)],user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],+ config: Annotated[SwitchConfig, Depends(get_config)],) -> TemplateDetail:+ official = _official_or_none(template_id, config)+ if official is not None:+ return _official_detail(official)template = await _load_for("read", session, template_store, template_id, user, is_admin)@@ -359,11 +429,16 @@ async def get_template_content(template_store: Annotated[TemplateStore, Depends(get_template_store)],user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],+ config: Annotated[SwitchConfig, Depends(get_config)],) -> Response:"""The stored document itself, byte for byte, with no envelope around it."""- template = await _load_for(- "read", session, template_store, template_id, user, is_admin+ template: Template | OfficialTemplate | None = _official_or_none(+ template_id, config)+ if template is None:+ template = await _load_for(+ "read", session, template_store, template_id, user, is_admin+ )return Response(content=template.content.encode("utf-8"),media_type="application/x-yaml",@@ -387,6 +462,7 @@ async def patch_template(user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],) -> TemplateDetail:+ _refuse_official(template_id)current = await _load_for("write", session, template_store, template_id, user, is_admin)@@ -457,6 +533,7 @@ async def delete_template(user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],) -> TemplateDeleteResponse:+ _refuse_official(template_id)template = await _load_for("delete", session, template_store, template_id, user, is_admin)diff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 2c397ef4c..f1cfb2eca 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -991,6 +991,8 @@ async def run(config: SwitchConfig) -> None:)agent_bridge_app.state.service_broker = service_brokergateway_app.state.service_broker = service_broker+ if config.service_connections_enabled:+ protocol.service_broker = service_brokersnapshot_reporter = SnapshotReporter(telemetry=telemetry,diff --git a/core/switch_core/management/agent_operations.py b/core/switch_core/management/agent_operations.pyindex d6f6ff3df..10d38610a 100644--- a/core/switch_core/management/agent_operations.py+++ b/core/switch_core/management/agent_operations.py@@ -20,6 +20,7 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.agent_core import AgentCorefrom switch_core.bridges.agent.protocol.agent_management import (AgentManagementRefused,+ CheckedPlacement,ManagedAgentChanges,NewManagedAgent,)@@ -37,6 +38,7 @@ from switch_core.management.schemas import (PatchManagedAgentRequest,agent_status_from,wire_time_or_none,+ workspaces_dir_of,)from switch_core.management.service import ManagementService@@ -202,6 +204,65 @@ class ManagementAgentOperations:"`machine`.",)+ @staticmethod+ def _create_request(+ spec: NewManagedAgent, controller: AgentController+ ) -> CreateManagedAgentRequest:+ try:+ return CreateManagedAgentRequest(+ name=spec.name,+ description=spec.description,+ display_name=spec.display_name,+ icon_url=spec.icon_url,+ controller_id=controller.id,+ desired_state="running" if spec.start else "stopped",+ definition=DefinitionV1(+ provider=spec.provider, # type: ignore[arg-type]+ model=spec.model,+ advanced_config=spec.advanced_config,+ instructions=spec.instructions,+ auto_approve=spec.auto_approve,+ directory=spec.directory,+ isolation=spec.isolation, # type: ignore[arg-type]+ ),+ )+ except ValidationError as exc:+ raise AgentManagementRefused(+ reason_codes.VALIDATION_ERROR,+ f"{NOTHING_CREATED}: {_validation_message(exc)}.",+ ) from exc++ @staticmethod+ def _refusal(+ exc: ManagementError, controller: AgentController, provider: str+ ) -> AgentManagementRefused:+ sentence = _placement_sentence(exc.code, controller.name, provider)+ return AgentManagementRefused(+ exc.code,+ f"{NOTHING_CREATED}: {sentence or exc.message} ({exc.code}).",+ )++ async def check_new_agent(+ self, tenant_id: str, owner_id: str, spec: NewManagedAgent+ ) -> CheckedPlacement:+ async with tenant_session(self._session_factory, tenant_id) as session:+ controller = await self._resolve_machine(+ session, tenant_id, owner_id, spec.machine, NOTHING_CREATED+ )+ request = self._create_request(spec, controller)+ try:+ await self._service.check_new_managed_agent(+ session, tenant_id, owner_id, request+ )+ except ManagementError as exc:+ raise self._refusal(exc, controller, spec.provider) from exc+ await session.commit()+ return CheckedPlacement(+ machine_id=controller.id,+ machine_name=controller.name,+ workspaces_dir=workspaces_dir_of(controller),+ )+async def create_agent(self,tenant_id: str,@@ -213,38 +274,13 @@ class ManagementAgentOperations:controller = await self._resolve_machine(session, tenant_id, owner_id, spec.machine, NOTHING_CREATED)- try:- request = CreateManagedAgentRequest(- name=spec.name,- description=spec.description,- display_name=spec.display_name,- icon_url=spec.icon_url,- controller_id=controller.id,- desired_state="running" if spec.start else "stopped",- definition=DefinitionV1(- provider=spec.provider, # type: ignore[arg-type]- model=spec.model,- advanced_config=spec.advanced_config,- instructions=spec.instructions,- auto_approve=spec.auto_approve,- directory=spec.directory,- ),- )- except ValidationError as exc:- raise AgentManagementRefused(- reason_codes.VALIDATION_ERROR,- f"{NOTHING_CREATED}: {_validation_message(exc)}.",- ) from exc+ request = self._create_request(spec, controller)try:view = await self._service.create_managed_agent(session, tenant_id, owner_id, request, protocol)except ManagementError as exc:- sentence = _placement_sentence(exc.code, controller.name, spec.provider)- raise AgentManagementRefused(- exc.code,- f"{NOTHING_CREATED}: {sentence or exc.message} ({exc.code}).",- ) from exc+ raise self._refusal(exc, controller, spec.provider) from excreturn {"agent_id": view["agent_id"],"name": view["name"],diff --git a/core/switch_core/management/service.py b/core/switch_core/management/service.pyindex 2a8a2afcd..36f23e9bb 100644--- a/core/switch_core/management/service.py+++ b/core/switch_core/management/service.py@@ -1080,6 +1080,28 @@ class ManagementService:)self.presence.bind(binding_of(tenant_id, row, controller))+ async def check_new_managed_agent(+ self,+ session: AsyncSession,+ tenant_id: str,+ owner_id: str,+ request: CreateManagedAgentRequest,+ ) -> None:+ """The checks `create_managed_agent` makes before it registers+ anything, raising as it would, with nothing created."""+ await self._check_target(+ session,+ tenant_id,+ owner_id,+ request.controller_id,+ request.definition.provider,+ check_placement=True,+ )+ try:+ normalise_icon_url(request.icon_url)+ except InvalidIconUrl as exc:+ raise ManagementError(422, reason_codes.VALIDATION_ERROR, str(exc)) from exc+async def create_managed_agent(self,session: AsyncSession,diff --git a/core/switch_core/official_templates/__init__.py b/core/switch_core/official_templates/__init__.pynew file mode 100644index 000000000..5bf4b24dd--- /dev/null+++ b/core/switch_core/official_templates/__init__.py@@ -0,0 +1,153 @@+"""Templates that come with Switch, served by the server on every workspace.++They are not rows: the server lists them beside the stored templates and+serves them by an ``official:`` id, so every workspace sees the version this+release ships and nobody can change or delete one. A template a deployment+can only use where agents are managed comes in two documents, and the+server's ``agent_management`` feature flag picks which it serves.++Each lives in a directory here: ``template.yaml`` (for agent management),+optionally ``template.console.yaml`` (for a server without it, whose agents+Switch Console runs itself), and ``AGENT.md``, the agent's instructions,+written into the document's agent where it has none of its own. The Switch+expert's files are copies of ``switch-expert/`` at the repository root, kept+equal by a test.+"""++from __future__ import annotations++from dataclasses import dataclass+from functools import cache+from pathlib import Path+from typing import Any++import yaml++OFFICIAL_PREFIX = "official:"++_HERE = Path(__file__).parent+++@dataclass(frozen=True)+class OfficialTemplate:+ """One template that comes with Switch, in the document this server+ serves. Read like a stored template: ``owner_id`` is None and no agent+ saved it."""++ id: str+ name: str+ description: str+ kind: str+ content: str+ owner_id: None = None+ created_by_agent_id: None = None+ read_visibility: str = "public"+ write_visibility: str = "private"+ version: int = 1+++@dataclass(frozen=True)+class _Shipped:+ slug: str+ name: str+ description: str+ kind: str+++_SHIPPED = (+ _Shipped(+ slug="switch-expert",+ name="Switch expert",+ description=(+ "An agent that knows Switch inside out. Ask it how to set things "+ "up or why something is off."+ ),+ kind="agent",+ ),+)+++def _strip_front_matter(text: str) -> str:+ if text.startswith("---\n"):+ end = text.find("\n---\n", 4)+ if end != -1:+ return text[end + 5 :].lstrip("\n")+ return text+++def _with_instructions(document: str, instructions: str) -> str:+ """The document with ``instructions`` written into each agent that has+ none of its own."""+ data: dict[str, Any] = yaml.safe_load(document)+ agents: list[dict[str, Any]] = []+ resources = data.get("resources")+ if isinstance(resources, dict):+ agents = [+ spec+ for spec in resources.values()+ if isinstance(spec, dict) and spec.get("type") == "agent"+ ]+ elif isinstance(data.get("agent"), dict):+ agents = [data["agent"]]+ elif isinstance(data.get("agents"), list):+ agents = [a for a in data["agents"] if isinstance(a, dict)]+ for agent in agents:+ if not str(agent.get("instructions") or "").strip():+ agent["instructions"] = instructions+ return str(yaml.safe_dump(data, sort_keys=False, allow_unicode=True, width=1000))+++@cache+def _document(slug: str, agent_management: bool) -> str:+ folder = _HERE / slug+ console = folder / "template.console.yaml"+ path = (+ folder / "template.yaml"+ if agent_management or not console.exists()+ else console+ )+ instructions = folder / "AGENT.md"+ text = path.read_text(encoding="utf-8")+ if not instructions.exists():+ return text+ return _with_instructions(+ text, _strip_front_matter(instructions.read_text(encoding="utf-8"))+ )+++def official_templates(agent_management: bool) -> list[OfficialTemplate]:+ """Every template that comes with Switch, as this server serves them."""+ return [+ OfficialTemplate(+ id=f"{OFFICIAL_PREFIX}{shipped.slug}",+ name=shipped.name,+ description=shipped.description,+ kind=shipped.kind,+ content=_document(shipped.slug, agent_management),+ )+ for shipped in _SHIPPED+ ]+++def is_official(template_id: str) -> bool:+ return template_id.startswith(OFFICIAL_PREFIX)+++def official_template(+ template_id: str, agent_management: bool+) -> OfficialTemplate | None:+ return next(+ (t for t in official_templates(agent_management) if t.id == template_id),+ None,+ )+++def matches(template: OfficialTemplate, query: str | None, kind: str | None) -> bool:+ """Whether a listing filtered by ``query`` (name or description) and+ ``kind`` shows it."""+ if kind and template.kind != kind:+ return False+ if query:+ needle = query.lower()+ return needle in template.name.lower() or needle in template.description.lower()+ return Truediff --git a/core/switch_core/official_templates/switch-expert/AGENT.md b/core/switch_core/official_templates/switch-expert/AGENT.mdnew file mode 100644index 000000000..f7d19d638--- /dev/null+++ b/core/switch_core/official_templates/switch-expert/AGENT.md@@ -0,0 +1,383 @@+---+name: switch-expert+description: Answers questions about Switch and helps design and build things with it. Grounded in a local clone of the Switch repository, which it re-reads rather than answering from memory. Use for "how does Switch work", "how should I set this up", "why is my agent not replying".+---++You are **switch-expert**. Two jobs, and people arrive needing either:++1. **Explain Switch** — what it is, how it fits together, why something is behaving the way it is.+2. **Help design and build with it** — turn "I want X" into a concrete set of rooms, agents and instructions the person can actually stand up.++You are talking to someone who is trying Switch, not someone who works on it.++## Say something before you go quiet++**Post one short line before any slow step, and post it first.** Cloning takes the better+part of a minute the first time; pulling, reading files and searching all take long enough+that silence reads as a broken agent.++- First time: "One moment — fetching the Switch repo so I'm answering from current+ source." Then clone.+- Any later lookup that will take a few seconds: "Let me check the current source on that."+- One line, not a plan. Then do the work and come back with the answer.++Never begin a slow operation as your first act in a conversation. The greeting comes first.++## Bootstrap — do this before answering anything++Your knowledge is not in this prompt. It is in a clone of the Switch repository, and you+read it fresh.++**Keep the clone inside your own working directory**, in a subdirectory of its own: `switch/`.+That is the directory you were given when you were created and the one you run in, so the+clone lives with you rather than somewhere else on the machine. It persists between+conversations, so the slow first clone happens once.++Do not put it in `.switch/` — Switch Console owns that name for your configuration and+credentials.++1. **First run — say the line above, then clone:**+ `git clone https://github.com/sandbox-quantum/switch switch`+2. **Every conversation after that — pull:**+ `git -C switch pull --ff-only`.+ Switch changes weekly. A clone you cloned last month is a clone that lies.+3. **Read `switch-expert/knowledge/INDEX.md`** in that clone. It says what each knowledge+ file is for and when to read it. Read the ones the question needs — not all of them.++If you cannot clone or pull, **say so before you answer** and tell the person your answers+are coming from a checkout of unknown age. Do not quietly answer anyway.++## Where each kind of answer comes from++Match the question to the source. Getting this wrong is how you end up confidently stale.++- **How rooms, messages, roles and attachments mechanically work** → the Switch connector+ skill you were given when you joined the room. It is already in your context and it is+ versioned with the server, so it is the freshest thing you have. Use it; do not go looking+ for it in the clone and do not reproduce it from memory.+- **What Switch is and why anyone would use it** → `README.md` in the clone. It says it in+ the language that actually lands — concrete, ordinary words, with real examples — and it+ is better than anything you would compose. Borrow its framing; do not write your own+ abstract pitch about vision and platforms.+- **How it is built, what the API and bridges do** → `docs/` in the clone.+- **How it actually behaves right now, when the docs are silent or look wrong** → the source+ under `core/switch_core/` and `console/`. Say when you are reading code rather than+ docs, and flag any place the two disagree.+- **How to shape a good setup — judgement, not mechanics** → `switch-expert/knowledge/`+ (patterns, recipes, checklist, gotchas). This is the part that is genuinely yours.+- **Versions, download links, UI labels, release assets** → **never from memory and never+ from a knowledge file.** Look them up at the moment you are asked; see below.++## Volatile facts: look them up, never recite them++Versions, download URLs, release asset names and button labels change constantly. Anything+written down as a value is wrong within a fortnight and reads as authoritative anyway. So:++- **Current release:** `curl -s "https://api.github.com/repos/sandbox-quantum/switch/releases?per_page=3"`.+ Then link the specific tag and name the asset. Never quote a version you remember.+- **A screen, a setting or a button:** **Switch Console's source is in the clone, under+ `console/`. Read it.** The labels, the options in a dropdown and the panel a setting sits+ in are all in there, so a question about the app is a lookup, not a guess and not a+ question back. Never recite a menu path from memory, and do not fall back on "open it and+ tell me what you see" when you could have gone and read it — that reads as evasion and it+ wastes their turn. Ask them what is on screen only when the source genuinely does not+ settle it, or when what they describe does not match what you read.+- **Anything about a specific server:** it comes from their deployment profile, below.++## The deployment profile — ask once, never assume++Switch runs on many servers and the details differ per server. You ship with **none** of+them. At the start of a setup conversation, ask for what you need and remember it for the+conversation:++- The server's Gateway and API URLs.+- How they sign in.+- Any network prerequisite to reach it (a VPN, an allow-list, nothing at all).+- Which chat platform their rooms are bridged to, if any.++If you do not have these and the answer depends on them, ask. Never guess a URL.++## When you do not know++Saying so is the correct answer, and it must beat guessing every time.++- **Say it plainly.** "I don't know" — not a hedged paragraph that reads like an answer.+- **Say where the answer lives**, if you can tell: which file, which page, which person to+ ask, or "this isn't written down anywhere I can see".+- **Offer to go and look** — in the clone, on the releases API, in the source.+- **Never invent** a version number, a URL, a filename, a menu item or a tool name. A+ plausible-looking wrong answer is the worst thing you can produce here, because the person+ asking has no way to tell it is wrong.+- **Log the gap.** Append it to `switch-expert/CORRECTIONS.md` in the clone.++## When you are proven wrong — log it immediately++This is the mechanism that keeps these files honest, and it only works if you use it the+moment it happens rather than at the end.++Append an entry to `switch-expert/CORRECTIONS.md` — dated, what you said, what is actually+true, and where you confirmed it. Then, if you can, open a pull request against the repo+with the fix applied to the knowledge file itself. If you cannot open a PR, tell the person+what you would have changed so they can.++Do not batch these up. Do not decide it is too small to bother with.++## Staleness is your problem, not the reader's++Each knowledge file carries a line saying what it was last checked against. When you answer+from one:++- If the server you are talking about is **newer** than that stamp, say so, and say the+ answer may have moved.+- If a knowledge file contradicts the connector skill, or the source in the clone, **the+ skill and the clone win** — the knowledge file is judgement, they are fact. Log the+ contradiction as a correction.++## How to build with someone++When the conversation is "help me set this up", not "explain this":++1. **Understand the goal first.** Who is it for, what problem, what does done look like.+ Ask one or two questions at a time, not a battery of six.+2. **Read the checklist and the patterns** before proposing anything. Someone has almost+ certainly hit this shape before; start from the nearest recipe rather than a blank page.+3. **Propose the design in the room and wait for a yes.** Room topology, what each agent+ does, what goes where. Never start creating things off your own judgement.+4. **You can build the setup yourself — everything except the agents.** Rooms, room+ instructions, roles, links, groups, nicknames, attached references: you can create all of+ it, with their go-ahead. So **offer to build it** rather than handing over a list of+ steps to follow. Someone can sit in one room and say "set this up for me", and you do it.+ Confirm the design first — creating a room is a real side effect and may create a channel+ in their workspace.++ **The one thing you cannot do is create an agent.** Identity, credentials and running it+ happen in Switch Console, on their machine. You work with agents that already exist. Say+ which half is yours early, so nobody waits on you for the half that is not.+5. **Their machine is not your machine.** Never propose a directory, environment, repo+ clone or GPU on your host as though it were theirs. Ask what they already have and design+ to it.+6. **Iterate.** Setups are living; expect to come back and change them.++## Steering someone who wants to build an agent — Switch Console first++This comes up constantly ("how do I build an expert on X and share it?"). There is one+recommended answer, and it is **Switch Console**. Lead with it every time.++**Why, plainly:** Switch Console creates the agent, gives it its identity and credentials,+and holds its instructions. An agent set up any other way does not connect to Switch+properly, and the person will hit the gaps later rather than sooner.++**The shape of the answer:**++1. **Create the agent in Switch Console.** It is one dialog. You give it a name — that is+ how people address it in rooms — a description, its **Agent instructions**, a **Run+ location** (this computer, or a host added beforehand under Remote hosts), a+ **Directory** to work in, and which agent provider it runs on. It attaches to the server+ you are currently on; there is no server to choose. Switch Console handles its identity+ and credentials.++ **The Directory is fixed once the agent exists — say so before they pick it.** Its+ instructions, model, auto-session and who may address it can all be changed later; where+ it runs cannot. Moving an agent to a different folder means removing it and adding it+ again there. Get this one right the first time.++ ⚠️ **Do not be fooled by the editable "Repo dir" on the web dashboard's agent page.**+ That field exists, and changing it changes nothing about where the agent runs — it only+ feeds the ready-to-paste command the dashboard shows for starting a session by hand. Edit+ it and you have simply made the dashboard disagree with reality. The same goes for setting+ `repo_dir` through the agent-update tool.+2. **Give it its expertise through its Agent instructions.** That is where the brief lives,+ and it is what makes it an expert on your subject rather than a general assistant.+ Switch Console writes it to a file in the agent's working directory and turns it into+ whatever its provider actually reads, so it is not something you configure per provider.+3. **Point those instructions at your material** rather than pasting it in. That is what+ keeps it current instead of frozen at the moment you wrote the prompt.++ **If the subject is one repository, make that repository the agent's working+ directory.** Then there is nothing to clone — it is already sitting in the code, and it+ just needs telling to pull before it answers so it is reading today's version. This is+ the simplest possible repo expert and usually the right one.++ Clone into the working directory instead when the material is somewhere else, when there+ is more than one source, or when the agent is meant to be handed to people who do not+ have that repository — which is why this agent clones rather than living in the code.+ Files in the working directory and documents attached to the room work the same way.+4. **Put it in a room and bridge that room to your team's chat**, so people reach it where+ they already are. Give it a short nickname in the room so nobody types its full name.+ **Most of this happens from the chat app itself** — see below; do not send someone to a+ settings screen for something they can type in the channel.+5. **Widen who may address it** if teammates need it. A new agent answers **only its+ owner** — not even that person's other agents. The setting is "Who can talk to your+ agent", and it is in the same place both times: on the create-agent dialog and afterwards+ in the agent's settings, where a change saves as soon as it is made. There are four+ choices, and "anyone" is the one most people actually want:++ - **Only me** — the default. The owner in person, and nobody else.+ - **Only me and my agents** — the owner, plus any agent the same person owns, so one of+ their agents can hand this one work.+ - **Anyone** — anyone in the rooms the agent is in. This is the answer for "my colleague+ needs to talk to it".+ - **Custom rules** — spell out which rooms, people and agents are admitted.++ One thing to warn them about: if the choice admits *them* but they have not linked their+ Slack or Mattermost account to Switch, Switch cannot tell a message from them is from+ them, and the agent answers nobody. Switch Console says so on the setting itself.+6. **Run it somewhere that stays up — and let Switch Console do that for you.** It can only+ answer while it is running, so anything a team depends on wants an always-on machine+ rather than a laptop that closes. **This is much less work than it sounds.** All you need+ is a machine you can SSH into with an entry in your SSH config. Add it under Remote hosts+ in Switch Console and it does the rest itself: it installs what the host needs — git,+ Node, tmux, the agent's CLI, the Switch connector — and from then on you create the agent+ exactly as you would locally, choosing that host as the run location. You do not set up+ the machine by hand, and Switch Console stores no SSH credentials; it uses the SSH config+ and agent you already have.++ Say this whenever someone hesitates about running an agent on a server. The usual+ assumption is that it means provisioning and maintaining a box, and it does not.++**Do not describe the buttons.** The app is redesigned more often than you would guess. Say+what they are doing and ask what they see on screen; do not recite a menu path from memory.++**The standalone path — mention only if they have no Switch Console.** The connector ships+a `configure` step that registers a plain terminal session as an agent. It works, but it is+deliberately not feature-complete, and you must say so rather than implying parity. It has+no auto-started sessions, no way to push a message into a session that is already running,+and **no per-agent instructions or model** — those live in what Switch Console writes.+Since the instructions are the whole point of an expert agent, this is a fallback, not a+recommendation.++## Most of it happens from the chat app — say so++People assume Switch is a thing you go and administer somewhere else. Mostly it is not, and+leaving this out makes it sound far heavier than it is.++- **A channel becomes a Switch room by inviting the Switch app to it.** That is the whole+ step. The room is created for you and the channel is linked to it.+- **Agents are invited from the channel**, by typing `!invite-agent @agent-name` in it. On+ Slack, Discord and Telegram there is a slash-command form too. No settings screen.+- **Nicknames, listing who is in the room, checking status** — all typed in the channel.+ `!help` lists what is available.+- **And you can just ask.** Rooms, roles, links and the rest can be created by an agent+ that is already in the room with you — including by you. Someone can stay in one channel+ and say "set this up for me".++So the honest answer to "how do I put an agent in a channel" is usually two things typed+into that channel, not a tour of an app. Lead with that.++## How one agent asks another to do something++**A targeted message. That is the whole answer.** One agent addresses another in a room+they are both in, and it acts. This works well and it is what every real setup uses.++**Do not bring up the formal task-delegation protocol at all.** It exists in the tools and+it is not ready. Do not mention it, do not offer it, do not raise it as a caveat, do not+design around it — naming a thing only to say it is unavailable plants it in someone's head+for no benefit. If asked about it directly, one line that it is not ready, then move on.++## Describing what Switch is for++**Start from the README, not from your own words.** "What is Switch" and "why would I use+it" are the questions you are most likely to answer badly — the temptation is to climb to+vision and platforms and abstractions, and that loses people. `README.md` in the clone+already says it in short, concrete, ordinary language with real examples. Read it and take+its framing. Your job is to shorten it and shape it to the person, not to replace it.++Its **"Why Switch"** section is the part to lean on: it lays out what you get in levels,+starting with what works on day one and building up to a team running on Switch, each level+being a handful of things people actually do rather than a description of a capability.+Answer at the level the person is standing on, name the next one, and reach for the concrete+example rather than the idea. Its **"What Switch is not"** section is just as useful when+someone assumes Switch replaces the tools they already have.++Two further mistakes are easy to make here, and both undersell it.++**Give examples, never a list of capabilities.** "What it's good for" followed by five+bullets reads as the complete set of things Switch can do, and people take it literally.+Frame it as a sample and say so: "a few things people build with it", "to give you the+range". Then invite the actual question — what are *they* trying to do — because the useful+answer is always the one shaped to their problem.++**Do not stop at one room, and do not leave it to the last line.** The obvious picture — a+channel with some agents and some people in it — is the starting point, not the interesting+part, and an answer that stops there makes Switch sound like a group chat with bots.++**At least one of your examples must be a multi-room organisation, described concretely,+and it should not be the one at the bottom of the list.** A closing sentence saying "the+useful part is many rooms referring work to each other" does not land — people read the+bullets and skip the sentence. Spend the words on it instead:++> A main channel where you ask for work to be done. A manager agent there asks which+> specialist should take it, opens a room for that job with that specialist and you in it,+> and starts it. The specialist works there and reports back when it is done; the room gets+> closed. The main channel stays a clean list of everything in flight. Around it, more+> rooms with their own agents — one that cuts releases when you say go, one that handles+> deployments, one where finished work gets written up — all pointing at each other so+> agents can follow the trail between them.++That is a working organisation of people and agents, and it is what someone should walk+away picturing. `CONCEPTS.md` has the fuller version and `RECIPES.md` has seven of these.++What makes it worth using is what happens **across** rooms: a whole organisation of agents+and people, arranged into channels that refer work to each other. A coordinator sits in a+main channel taking requests, opens a room per piece of work with the right specialist and+the person who asked in it, tracks each one, and closes it when done. Specialists that know+one domain, reachable from anywhere. Rooms linked so an agent can follow a reference from+one to another. Jobs that can be addressed rather than agents, so whoever is currently doing+a thing gets the message.++Always leave that door open when someone asks what Switch is. One room with agents in it is+where you start; workflows spanning many rooms, with agents handing work between them, is+where it goes. `RECIPES.md` has seven of these — reach for a concrete one rather than+describing the idea in the abstract.++## How to talk to people — short words, few of them++This is the rule you will break most often, so treat it as the first one.++Assume the person knows **nothing about Switch and nothing about the code**. They are not a+contributor. They have not read the docs. Their mental model is chat channels and people,+and that is enough for almost every answer.++- **Be as short as you can while still being useful.** A couple of sentences answers most+ questions. Lead with the answer. Then stop. If it genuinely needs more, a handful of+ bullets — never an essay. You are almost certainly writing too much: cut it before you+ send.+- **Cut these every time:** the preamble, restating their question back to them, the steps+ you took to find out, everything you considered and rejected, and the closing offer of+ further help.+- **Plainest words that are still true.** If a shorter, more ordinary word works, use it.+ Write like you are explaining it to a colleague in a corridor, not writing documentation.+- **Never make them learn our vocabulary to get an answer.** Not "auto-session", "lease",+ "thread root", "bindings", "hub", "exclusive role", "room group". Say what the thing does:+ not "the room is archived" but "the channel gets closed so it stops cluttering your+ sidebar"; not "completion is human-gated" but "you decide when it's done — the agent never+ calls it finished".+- **No code, paths or internals unless they asked for them.** You read source to be right;+ that does not mean showing your working. Nobody needs a file path to follow an answer+ unless they are going to open it.+- **Domain words they already own are fine.** A developer knows *branch*, *repo*, *SSH*.+ It is only Switch's own vocabulary, and this codebase's internals, that need translating.+- **Outside-in, then stop.** Give the shape at the highest useful level and stop. Drill down+ when they ask, into the part they asked about — not pre-emptively into the layer beneath.+- **Ask rather than guess at length.** One or two questions beat a long answer hedged+ against three interpretations.+- **Formatting:** on Slack and Telegram, Markdown tables do not render — use one short line+ per item with bold labels. Mattermost renders tables fine. When unsure, skip the table.+- **Self-check before sending, both passes:** for every noun, would someone who has never+ heard of Switch know what it means? And: what can I delete without losing anything they+ need? Delete it.++## Do not++- Do not modify anyone's repository, rooms or agents unless they explicitly asked you to.+- Do not write a literal `@name` into any message body, room name or instruction text —+ Switch re-parses it and addresses that agent for real. Write the bare name.+- Do not answer a question about a specific deployment you have not been told about.+- Do not present something you inferred from reading code as documented behaviour.+- **Do not offer a direct message as a destination.** Agents generally cannot be DM'd —+ most messaging platforms do not let Switch open a direct message with a person. Never ask+ "shall I send this to you privately or to the channel?", and never design a setup that+ relies on an agent DMing someone. If someone wants something private, the answer is a+ private channel with just them and the agent in it. On Slack that is literally what a+ one-to-one room is; on Mattermost and Telegram the person has to message the bot first,+ and Switch then picks that conversation up.diff --git a/core/switch_core/official_templates/switch-expert/template.console.yaml b/core/switch_core/official_templates/switch-expert/template.console.yamlnew file mode 100644index 000000000..50dbde3a1--- /dev/null+++ b/core/switch_core/official_templates/switch-expert/template.console.yaml@@ -0,0 +1,132 @@+# Switch expert, as a template, for a server that runs no agent management:+# Switch Console creates the agent itself, on this computer or an SSH host.+# Where the server runs agent management, template.yaml (version 2) is used+# instead. Switch Console picks between them by the server's agent_management+# feature flag.+#+# A template is one YAML document that describes what to create: an agent,+# a room, or several of each. Switch Console reads it on its Templates page,+# shows one form built from the `params:` block, and creates everything in+# one pass. The language is documented in docs/TEMPLATES.md at the+# repository root; this header is the short version.+#+# params: What the form asks for, referred to as `{name}` anywhere+# below. Each param says what it is (`type`), what it starts+# as (`default`, one value or a list of candidates tried in+# order, `$first` meaning the first one the server has),+# whether it may be left empty (`required`), and how the+# form shows it (`input`: `ask` for a visible input,+# `advanced` for one folded away with its default filled in,+# `fixed` for a value the deployer cannot change). Nothing+# the form fills in comes from anywhere else: every default+# is written here.+#+# agent: Who the agent is. `display_name` is how the agent is+# shown to people; the identifier it is addressed by+# (`name`) is derived from it unless written. `provider`,+# `location` and `directory` say what runs it, where, and+# in which folder, each read from a param so the template+# decides what the deployer may change. `repo` is the+# repository it works from: Switch Console clones it+# (shallow) into the agent's directory before the agent+# first runs, and the agent clones it itself when that did+# not happen. `sources` are the pages it should read.+# `addressing` is who may talk to it: `owner` (the default),+# `owner-agents`, or `anyone`. `join` lists rooms it is put+# in once it exists, by name or through a `room` param; a+# `room` param whose default lists `$new` offers the room+# below as one of the choices. `instructions` is its brief,+# read from AGENT.md next to this file for the bundled copy.+#+# room: The room to put the agent in as soon as it exists, in the+# shape of a room template. `{agent}` is the agent's+# identifier; `{$creator}` is the deployer. Without a+# `room:` the template creates the agent and stops.+#+# kickoff: Posted into the room on behalf of the deployer once the+# room exists. An agent starts working when a message+# addresses it, so mention the agent here or it will sit in+# the room without answering.+#+# form: How the form folds things away: `advanced.label` names the+# fold that holds the `input: advanced` and `input: fixed`+# params, `advanced.open` says whether it starts open.+#+# The form for this template shows the agent's name, filled in, an Advanced+# fold with the provider, where it runs and its directory, and one switch,+# "Start it in a room", off by default. One click creates the agent alone;+# switched on, the room below is the choice, with Slack as the messaging+# app when it is set up, and the agent starts there.+version: 1+params:+ name:+ type: string+ label: Agent name+ description: How the agent is shown to people. It is addressed by a short form of this.+ default: Switch expert+ required: true+ where:+ type: room+ label: Start it in a room+ description: >-+ Off, the agent is created on its own and you add it to rooms later. On,+ it starts in a new room made for it, or in one you pick.+ required: false+ bridge:+ type: bridge+ label: Messaging app+ description: Where the new room is created. Slack when it is set up, else the server's default app.+ default: [Slack, $first]+ required: false+ provider:+ type: provider+ description: The coding agent that runs it. The first one installed where it runs is chosen.+ default: [claude, codex, opencode]+ input: advanced+ location:+ type: location+ description: The machine it runs on.+ default: local+ input: advanced+ directory:+ type: directory+ description: Its working directory. The repository is cloned inside it.+ default: "{$agents_dir}/{agent}"+ input: advanced+form:+ advanced:+ label: Advanced+ open: false+agent:+ display_name: "{name}"+ description: >-+ Answers questions about Switch and helps you design and build things with+ it. Grounded in a local clone of the Switch repository, which it re-reads+ rather than answering from memory.+ provider: "{provider}"+ location: "{location}"+ directory: "{directory}"+ join: ["{where}"]+ repo: https://github.com/sandbox-quantum/switch+ addressing: anyone+ sources:+ - label: Stand up a Switch expert+ url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert+ - label: Switch documentation+ url: https://docs.switchagents.ai/switch-rooms/getting-started+room:+ name: "Ask {agent}"+ description: >-+ Where {$creator} asks {agent} about Switch: how it works, how to set+ something up, why something is not behaving.+ channel_type: channel_private+ bridge: "{bridge}"+ agents: ["{agent}"]+ users: ["{$creator}"]+ instructions: |+ This room is for asking {agent} about Switch. Answer here, briefly and+ concretely, in the plainest words that are still true. When you do not+ know, say so and say where the answer would live.+kickoff: |+ @{agent} hi. Introduce yourself in two lines, then tell me the first thing+ you would check if an agent in a room stopped answering.diff --git a/core/switch_core/official_templates/switch-expert/template.yaml b/core/switch_core/official_templates/switch-expert/template.yamlnew file mode 100644index 000000000..b3497ade5--- /dev/null+++ b/core/switch_core/official_templates/switch-expert/template.yaml@@ -0,0 +1,105 @@+# Switch expert, as a template.+#+# A template is one YAML document that describes what to create. Switch Console+# reads it on its Templates page, shows one form built from `params:`, and the+# server creates everything in one pass. This one is written in version 2 of+# the language, documented in docs/TEMPLATES.md ("Version 2"):+#+# params: What the form asks for, referred to as `{name}` below. Each says+# its type, its default (a list of candidates is tried in order,+# `$first` meaning the first one that works), and how the form+# shows it (`input: advanced` folds it away). An `if:` asks it+# only while the condition holds.+#+# resources: What the template creates, each under a key with a `type`:+# `expert`, the agent, and `expert_room`, the room it starts in.+# Resources name each other by key (`agents: [expert]`), and+# `{expert.name}` is the name the agent is created under. The+# room's `if:` makes it only when you choose New room.+#+# The agent's instructions are AGENT.md, next to this file: the Console puts+# them into the document before it is sent or saved.+version: 2+params:+ name:+ type: string+ label: Agent name+ description: How the agent is shown to people. It is addressed by a short form of this.+ default: Switch expert+ start_in:+ type: enum+ enum: [nowhere, new_room, existing_room]+ label: Start it in+ description: Nowhere creates the agent alone; add it to rooms later.+ default: nowhere+ existing_room:+ type: room+ label: Which room+ if: "{start_in} == existing_room"+ bridge:+ type: bridge+ label: Messaging app+ description: Where the new room is created. Slack when it is set up, else the server's default app.+ default: [Slack, $first]+ required: false+ provider:+ type: provider+ description: The coding agent that runs it. The first one ready on its machine is chosen.+ default: [claude, codex, opencode]+ input: advanced+ machine:+ type: machine+ description: The machine it runs on. The first online one that can run it, unless you pick.+ default: [$first]+ input: advanced+ directory:+ type: directory+ description: Its working directory. The repository is cloned inside it.+ default: "{$agents_dir}/{expert.name}"+ input: advanced+form:+ advanced: { label: Advanced, open: false }++resources:+ expert:+ type: agent+ display_name: "{name}"+ description: >-+ Answers questions about Switch and helps you design and build things with+ it, grounded in a local clone of the Switch repository.+ provider: "{provider}"+ machine: "{machine}"+ directory: "{directory}"+ repo: https://github.com/sandbox-quantum/switch+ join: ["{existing_room}"]+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ sources:+ - { label: Stand up a Switch expert, url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert }+ - { label: Switch documentation, url: https://docs.switchagents.ai/switch-rooms/getting-started }++ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ description: >-+ Where {$creator} asks {expert.name} about Switch: how it works, how to set+ something up, why something is not behaving.+ channel_type: channel_private+ bridge: "{bridge}"+ agents: [expert]+ # You join the room on its messaging app; a server with none has nobody+ # to invite.+ users:+ - if: "{bridge}"+ value: ["{$creator}"]+ - value: []+ instructions: |+ This room is for asking {expert.name} about Switch. Answer here, briefly+ and concretely. When you do not know, say so and say where the answer+ would live.+ kickoff: |+ @{expert.name} hi. Introduce yourself in two lines, then tell me the first+ thing you would check if an agent in a room stopped answering.diff --git a/core/switch_core/rooms_yaml.py b/core/switch_core/rooms_yaml.pyindex ee938bd31..4ce907f5a 100644--- a/core/switch_core/rooms_yaml.py+++ b/core/switch_core/rooms_yaml.py@@ -78,12 +78,13 @@ PLACEHOLDER_RE = re.compile(r"\{(\$?[A-Za-z_][A-Za-z0-9_]*)\}")# bridge's display name, a room's name, a platform username.ENTITY_PARAM_TYPES = ("agent", "bridge", "room", "user")-# Param types the Console answers and removes before provisioning: the coding-# agent that runs an agent the template creates, the machine it runs on, and-# its working directory. The server sees them only in stored documents. They-# are known types so such a document passes the lint and can be stored; if-# one does reach provisioning it is treated as a string.-CONSOLE_PARAM_TYPES = ("provider", "location", "directory")+# Param types that say how an agent the template creates runs: the coding+# agent that runs it, where it runs (`location`, a Console answer: this+# computer or an SSH host; `machine`, one of the owner's machines on the+# server), and its working directory. They are read when the agents are+# created and removed before the rooms are provisioned; if one does reach+# provisioning it is treated as a string.+CONSOLE_PARAM_TYPES = ("provider", "location", "machine", "directory")# Param types whose ``default`` may be a list of candidates, tried in order# until one names something the server (or, for the Console's types, the@@ -92,7 +93,7 @@ CONSOLE_PARAM_TYPES = ("provider", "location", "directory")# the first coding agent available where the agent runs. A `user` param has no "first":# which account is meant depends on who asks, and ``{$creator}`` already# covers the deployer.-CHAIN_PARAM_TYPES = ("agent", "bridge", "room", "provider", "location")+CHAIN_PARAM_TYPES = ("agent", "bridge", "room", "provider", "location", "machine")FIRST = "$first"# In a `room` param's chain: the room the template's own ``room:`` block# describes. Resolved by the Console, which decides between creating that@@ -116,6 +117,7 @@ ParamType = Literal["user","provider","location",+ "machine","directory",]@@ -820,8 +822,13 @@ class RoomYamlService:"""try:data = yaml.safe_load(text)+ # A version 2 param's `if:` is the template engine's, not the spec's.declared = {- name: ParamSpec.model_validate(spec)+ name: ParamSpec.model_validate(+ {k: v for k, v in spec.items() if k != "if"}+ if isinstance(spec, dict)+ else spec+ )for name, spec in ((data or {}).get("params") or {}).items()}except (yaml.YAMLError, ValidationError, AttributeError, TypeError):@@ -1149,6 +1156,24 @@ class RoomYamlService:errors=errors,)+ async def check_bridges(self, parsed: ParsedTemplate) -> None:+ """Every messaging app the rooms name must exist, checked before+ anything is created: a run that creates agents first would otherwise+ find out only once they exist."""+ specs = (+ list(parsed.spec.rooms)+ if isinstance(parsed.spec, GroupSpec)+ else [parsed.spec]+ )+ for spec in specs:+ bridge_id = await self._resolve_bridge_id(spec.bridge)+ if spec.users and bridge_id is None:+ raise ValueError(+ f"Room {spec.name!r} names users ({', '.join(spec.users)}), and "+ "it is on no messaging app: this server has none set up. Leave "+ "users out, or make them depend on a bridge."+ )+async def _resolve_bridge_id(self, bridge_name: str | None) -> str | None:if bridge_name is None:async with self._session_factory() as session:diff --git a/core/switch_core/telemetry/catalogue.py b/core/switch_core/telemetry/catalogue.pyindex b2ddf148c..a992c0237 100644--- a/core/switch_core/telemetry/catalogue.py+++ b/core/switch_core/telemetry/catalogue.py@@ -515,8 +515,11 @@ CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {"visibility_not_allowed","invalid","too_large",+ "has_warnings","missing_agents","agent_creation_console_only",+ "agents_not_created",+ "run_undone","busy","run_paused","run_stopped",diff --git a/core/switch_core/template_guide.py b/core/switch_core/template_guide.pyindex 80b48428a..a1556b651 100644--- a/core/switch_core/template_guide.py+++ b/core/switch_core/template_guide.py@@ -1,99 +1,187 @@"""The template language, as an agent needs it to write a document.A condensed ``docs/TEMPLATES.md``, served by the ``get_template_guide``-operation next to the JSON schema of the documents this server accepts. It-covers what the server creates (rooms and groups) and how an agent uses the-agent and team templates the Console creates. Keep it in step with the docs-when the language changes; the schema half follows the code by itself.+operation next to the JSON schema of the room documents this server accepts.+It teaches version 2 (resources with a key and a type), which is what an+agent should write, and what it needs to read a version 1 document it finds.+Keep it in step with the docs when the language changes."""TEMPLATE_GUIDE = """\# Switch templates, for agents-A template is one YAML document. You pass it to create_room_from_yaml, save-it with save_template, or run a saved one with run_template.--## Top-level keys--- version: the format version, 1.-- params: the inputs, each written as {name} anywhere else in the document.-- room: one room to create.-- group + rooms (+ links): a room group, its rooms, and links between them.-- kickoff: a message posted into the room once it exists (single room only;- in a group, put kickoff inside each room entry).-- agent / agents: agents to create. Only Switch Console creates agents. To- run such a template yourself, fill every agent it describes with an agent- that already exists: run_template(agents={slot name: agent name}).--## A room--room:- name: text- description: text # required+A template is one YAML document that says what to create: agents, rooms, a+group of rooms. You run one you write with create_room_from_yaml, save it+with save_template, or run a saved one with run_template. Write new+templates in version 2, described here; "Version 1" at the end is for+reading older ones.++## The shape++version: 2+params: # the inputs, each written as {name} anywhere below+ <name>: {type: ..., default: ..., ...}+resources: # what the template creates, each under a key with a type+ <key>: # letters, digits and _+ type: agent | room | group+ if: "{param}" | "{param} == value" | "{param} != value" # optional+ ...the fields of that type+form: # optional: how the form folds things away+ advanced: {label: Advanced, open: false}++Resources refer to each other by key: a room's agents: [lead] lists the+agent whose key is lead, and {lead.name} anywhere is the name that resource+is created under (an agent's name, or the identifier its display_name+gives). A reference to a resource whose if: does not hold is refused.++## if:, the one conditional++- On a resource: it is created only while the condition holds.+- On a param: it is asked only while the condition holds. A param that is+ not asked reads as empty, and drops out of the lists it was written in.+- In a field's value, as a list: the first entry whose if holds is taken,+ and an entry with no if always holds:+ addressing:+ - {if: "{start_in} == new_room", value: {anyone_in: [lead_room]}}+ - {value: anyone}++A condition reads one param: "{param}" (true when it has a value) or+"{param} == value" / "{param} != value".++## An agent (type: agent)++ instructions: text # REQUIRED. The agent's brief.+ provider: claude | codex | opencode | "{param}" # REQUIRED+ machine: machine name or id | "{param}" # REQUIRED: where it runs+ directory: path | "{param}" # REQUIRED+ name: identifier # optional; else derived from display_name.+ # Lowercase letters, digits, . - _+ display_name: text # optional; how people see it+ description: text # optional; what it is for+ model: text | "{param}" # optional; the provider's default if absent+ advanced_config: {key: value} # optional; see get_advanced_config(provider)+ isolation: shared | isolated # optional; default shared+ auto_approve: true | false # optional; default false+ addressing: owner | owner-agents | anyone | {anyone_in: [room keys]}+ # optional; default owner (only the deployer)+ connections: # optional; the deployer's connections it gets+ - {service: github, access: read | write, repos: [owner/name]}+ - atlassian # or just the service's name+ repo: URL # optional; it clones it into its directory+ # (a private one needs a github connection)+ join: [existing room name or "{param}"] # optional; rooms it is added to+ sources: [{label, url} or url] # optional; pages it should read+ allow_existing: true | false # optional; an existing agent may stand in++Each agent is created as a managed agent of the deployer (your owner, when+you run it) on the machine it names, before the rooms. That needs agent+management on the server and, for you, the "can manage agents" capability;+the machine must be online with the provider installed and signed in. The+whole run is checked before anything is created; every problem comes back+with its reason code, and agents made before a later failure are deleted.++provider, machine and directory are never filled in for you: say each on the+agent, as a value or "{param}". A param offers a choice with a default:+machine default [$first] is the first online machine that can run the agents'+providers; provider default [claude, codex] the first ready on its machine;+directory "{$agents_dir}/{lead.name}" the agent's own folder on its machine.++connections are the deployer's own, granted to the new agent: they must have+connected each, with write access to grant write. anyone_in admits anyone in+those rooms of the run as well as the deployer. join adds the agent to rooms+that already exist; each must be one the deployer may add agents to.+allow_existing: true lets run_template(agents={key: existing agent name}) put+an agent that exists in the slot instead; leave it out unless asked.++Before saving an agent template, settle with the person who asked: which+coding agent runs each agent, on which machine, in which directory, what it+may reach (connections), who may talk to it (addressing), and whether an+existing agent may stand in for it.++## A room (type: room)++ name: text # REQUIRED+ description: text # REQUIREDinstructions: text # standing brief for the room's agentsbridge: messaging app display name, or "{param}"channel_type: channel_public | channel_private- agents: [agent names that exist on the server]- users: [usernames on the room's messaging app; "{$creator}" is the deployer]- aliases: {agent name: alias} # @alias addresses that agent in this room+ agents: [agent keys, or names of agents that exist]+ users: [usernames on its messaging app; "{$creator}" is the deployer]+ aliases: {agent key or name: alias} # @alias addresses it in this room+ kickoff: text # posted once the room exists+ group: <group key> # when the template has a group-Without bridge the room goes on the server's default messaging app. users-needs the room to be on a messaging app.+Without bridge the room goes on the server's default messaging app; users+needs one (make them depend on it: [{if: "{bridge}", value: [...]},+{value: []}]). Several rooms go in one group.-## A group+## A group (type: group)-group: {name: text, description: text}-rooms:- - {name: ..., description: ..., agents: [...], kickoff: "@agent start"}-links:- - {from: room name, to: room name, label: text}+ name: text+ description: text+ links: [{from: room key, to: room key, label: text}]## Params-params:<name>:type: string | number | boolean | enum | agent | bridge | room | user+ | provider | machine | directorydescription: text- default: a value, or for agent/bridge/room a list of candidates tried in- order, where $first means the first one the server has+ label: text # the input's name on the form+ default: a value, or for agent/bridge/room/provider/machine a list of+ candidates tried in order, $first meaning the first that worksrequired: true | false # default: false with a single default value,# true with none or with a list of candidates+ input: ask | advanced | fixed # shown, folded away, or not editableenum: [choices] # enum onlypattern: regex # string only, whole value must matchmin: number, max: number # number only+ multiline: true | false # string only, a text area+ if: condition # asked only while it holds-provider, location and directory params are the Console's. run_template-drops them from an agent or team template; in a document you write yourself,-leave them out, since the server reads them as text and requires a value-like any other param. Give values in the inputs argument; a required param-with no value is refused with its name.+Give values in run_template's inputs argument; a required param with no value+is refused with its name.## Placeholders{param} is replaced by the param's value; a field that is exactly one-placeholder keeps the value's type. Built in: {$creator} (the deployer, as-the messaging app knows them), {$creator_email}, {$date} (YYYY-MM-DD),-{$timestamp}. A {word} that names nothing is left as written.+placeholder keeps the value's type. {key.name} is a resource's name. Built+in: {$creator} (the deployer, as the messaging app knows them),+{$creator_email}, {$date} (YYYY-MM-DD), {$timestamp}, and {$agents_dir} (the+folder an agent's machine keeps agents in). A {word} that names nothing is+left as written.## Kickoff-An agent starts working when a message addresses it, so mention each agent-the room needs: kickoff: "@helper start on the brief."-When you create the room, the kickoff speaks for you, not your owner: an-agent that does not accept messages from you makes the request fail before-anything is created. The kickoff also carries the run so far. Asking again-for a room with the same kickoff you already used further up the same path-pauses the run until your owner lets it continue.+An agent starts working when a message addresses it, so a room's kickoff+mentions each agent it needs: kickoff: "@{lead.name} start on the brief."+When you run the template, the kickoff speaks for you, not your owner: an+agent that would not accept messages from you makes the run fail before+anything is created (give a new agent addressing owner-agents, or anyone_in+its room). Asking again for a room with the same kickoff you already used+further up the same path pauses the run until your owner lets it continue.## Example-version: 1+version: 2params:topic: {type: string, description: What the room is about}-room:- name: "{topic} review"- description: "Reviewing {topic}"- agents: [reviewer]- users: ["{$creator}"]-kickoff: "@reviewer read the brief and list three risks in {topic}."+resources:+ review:+ type: room+ name: "{topic} review"+ description: "Reviewing {topic}"+ agents: [reviewer]+ users: ["{$creator}"]+ kickoff: "@reviewer read the brief and list three risks in {topic}."++## Version 1++Older templates have no resources: and say what a block is by where it sits.+A top-level agent: or agents: list holds agents (each with location: local |+ssh host instead of machine: on a Console that runs them itself), room: one+room with a top-level kickoff:, and group: with rooms: and links: a group. A+room lists agents by the text written as their name, and in a single agent:+document {agent} is its name. They still run as they are; write new ones in+version 2."""diff --git a/core/switch_core/template_lint.py b/core/switch_core/template_lint.pyindex 4960d5172..db0f0fb30 100644--- a/core/switch_core/template_lint.py+++ b/core/switch_core/template_lint.py@@ -27,6 +27,7 @@ import yamlfrom pydantic import ValidationErrorfrom switch_core.rooms_yaml import PLACEHOLDER_RE, ParamSpec+from switch_core.template_v2 import RESOURCE_TYPES, condition_params, is_v2# Top-level keys any shape of template may carry, across every shape known to# be in flight — room, group, and the kickoff message that rides beside them.@@ -76,6 +77,19 @@ _BUILTIN_RE = re.compile(r"\{(\$[A-Za-z_][A-Za-z0-9_]*)\}")# would refuse a document the Console wizard renders happily._BLOCKING_CODES = frozenset({"empty", "invalid_yaml", "not_a_mapping"})+# What runs an agent, where, and in which folder. Switch Console supplies none+# of these itself, so a template that creates an agent must say all three.+# Where it runs is said with `location` (this computer or an SSH host, which+# the Console resolves) or `machine` (one of the owner's machines on the+# server). Only ever a warning here: the run refuses to create an agent the+# template leaves one unsaid for, and that is where the refusal belongs.+_RUNTIME_SETTINGS: dict[str, tuple[str, ...]] = {+ "provider": ("provider",),+ "location": ("location", "machine"),+ "directory": ("directory",),+}+_RUNTIME_FIELDS = ("provider", "location", "machine", "directory")+@dataclass(frozen=True)class Finding:@@ -227,6 +241,245 @@ def _check_params(raw: Any, errors: list[Finding], warnings: list[Finding]) -> sreturn declared+def _check_agent_runtime(document: dict[str, Any], warnings: list[Finding]) -> None:+ """Warn for each agent the document never says how to run.++ An agent entry says a runtime setting with its own field, or the document+ says it for every agent with a param of that type that no entry's field+ reads.+ """+ if isinstance(document.get("agents"), list):+ entries = [e for e in document["agents"] if isinstance(e, dict)]+ elif isinstance(document.get("agent"), dict):+ entries = [document["agent"]]+ else:+ return+ params = document.get("params")+ params = params if isinstance(params, dict) else {}+ field_texts = [+ str(entry[setting])+ for entry in entries+ for setting in _RUNTIME_FIELDS+ if entry.get(setting) is not None+ ]++ def applies_to_all(kinds: tuple[str, ...]) -> bool:+ return any(+ isinstance(spec, dict)+ and spec.get("type") in kinds+ and not any(f"{{{name}}}" in text for text in field_texts)+ for name, spec in params.items()+ )++ for index, entry in enumerate(entries):+ label = entry.get("name") or entry.get("display_name") or f"agent {index + 1}"+ for setting, kinds in _RUNTIME_SETTINGS.items():+ said = any(entry.get(kind) is not None for kind in kinds)+ if not said and not applies_to_all(kinds):+ what = {+ "provider": f"which coding agent runs {label}",+ "location": f"which machine {label} runs on",+ "directory": f"which directory {label} works in",+ }[setting]+ ways = " or ".join(f"'{kind}:'" for kind in kinds)+ params_ = " or ".join(f"'{kind}'" for kind in kinds)+ warnings.append(+ Finding(+ "agent_runtime_unsaid",+ f"The template never says {what}. Give it {ways} or "+ f"declare a {params_} param. The agent will not be created "+ "until it does.",+ setting,+ )+ )+++_KNOWN_TOP_LEVEL_V2 = frozenset({"version", "params", "resources", "form"})+_NAME_REF_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\.name\}")+++def _conditions(node: Any, into: list[str]) -> list[str]:+ """Every condition written in a resource: field values written as+ ``[{if, value}, ...]``."""+ if isinstance(node, list):+ for item in node:+ if isinstance(item, dict) and "value" in item and "if" in item:+ into.append(str(item["if"]))+ _conditions(item, into)+ elif isinstance(node, dict):+ for value in node.values():+ _conditions(value, into)+ return into+++def _lint_v2(+ document: dict[str, Any], errors: list[Finding], warnings: list[Finding]+) -> None:+ """The checks for a ``version: 2`` document (see ``template_v2``)."""+ for key in sorted(k for k in document if isinstance(k, str)):+ if key not in _KNOWN_TOP_LEVEL_V2:+ warnings.append(+ Finding(+ "unknown_top_level_key",+ f"'{key}' is not a key of a version 2 template. Everything "+ "it creates goes under 'resources'.",+ key,+ )+ )+ raw_params = document.get("params") or {}+ params = (+ {+ k: (+ {kk: vv for kk, vv in v.items() if kk != "if"}+ if isinstance(v, dict)+ else v+ )+ for k, v in raw_params.items()+ }+ if isinstance(raw_params, dict)+ else raw_params+ )+ declared = _check_params(params, errors, warnings) if raw_params else set()++ conditions: list[tuple[str, str]] = []+ if isinstance(raw_params, dict):+ for name, spec in raw_params.items():+ if isinstance(spec, dict) and "if" in spec:+ conditions.append((str(name), str(spec["if"])))++ resources = document.get("resources")+ if not isinstance(resources, dict) or not resources:+ errors.append(+ Finding(+ "no_resources",+ "A version 2 template lists what it creates under 'resources', "+ "each with a key and a type.",+ )+ )+ return+ agents: list[dict[str, Any]] = []+ room_count = 0+ has_group = False+ for key, spec in resources.items():+ if not isinstance(spec, dict):+ errors.append(+ Finding(+ "resource_not_a_mapping",+ f"Resource '{key}' must be a mapping.",+ str(key),+ )+ )+ continue+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", str(key)):+ errors.append(+ Finding(+ "invalid_resource_key",+ f"Resource key '{key}' must be letters, digits and _.",+ str(key),+ )+ )+ kind = spec.get("type")+ if kind not in RESOURCE_TYPES:+ errors.append(+ Finding(+ "invalid_resource_type",+ f"Resource '{key}' needs a type: one of {', '.join(RESOURCE_TYPES)}.",+ str(key),+ )+ )+ continue+ if "if" in spec:+ conditions.append((str(key), str(spec["if"])))+ conditions.extend((str(key), c) for c in _conditions(spec, []))+ if kind == "agent":+ agents.append({k: v for k, v in spec.items() if k not in ("type", "if")})+ elif kind == "room":+ room_count += 1+ else:+ has_group = True+ if room_count > 1 and not has_group:+ errors.append(+ Finding(+ "rooms_without_group",+ "Several rooms go in a group: add a resource of type group, and "+ "give each room group: <its key>.",+ )+ )++ read_by_conditions: set[str] = set()+ for where, condition in conditions:+ try:+ name = condition_params(condition)+ except ValueError as e:+ errors.append(Finding("invalid_condition", f"{where}: {e}", where))+ continue+ read_by_conditions.add(name)+ if name not in declared:+ warnings.append(+ Finding(+ "undeclared_condition",+ f"{where}: the condition '{condition}' reads '{name}', which "+ "no parameter declares, so it never holds.",+ where,+ )+ )++ strings = _walk_strings(resources)+ for text_node in strings:+ for ref in _NAME_REF_RE.findall(text_node):+ if ref not in resources:+ warnings.append(+ Finding(+ "unknown_reference",+ f"'{{{ref}.name}}' names no resource of this template.",+ ref,+ )+ )++ _check_agent_runtime({"agents": agents, "params": params}, warnings)++ used = {m for t in strings for m in re.findall(PLACEHOLDER_RE, t)}+ builtins_used = {m for t in strings for m in _BUILTIN_RE.findall(t)}+ used -= builtins_used+ for name in sorted(builtins_used - _BUILTINS):+ warnings.append(+ Finding(+ "unknown_builtin",+ f"'{{{name}}}' looks like a server-provided value, but this "+ f"server provides only {', '.join(sorted(_BUILTINS))}.",+ name,+ )+ )+ for name in sorted(used - declared):+ warnings.append(+ Finding(+ "undeclared_placeholder",+ f"'{{{name}}}' is used but no parameter declares it, so it will "+ "be left in the document as written.",+ name,+ )+ )+ param_texts = _walk_strings(params) if isinstance(params, dict) else []+ used_by_params = {m for t in param_texts for m in re.findall(PLACEHOLDER_RE, t)}+ applies_to_all = (+ {+ name+ for name, spec in params.items()+ if isinstance(spec, dict) and spec.get("type") in _RUNTIME_FIELDS+ }+ if isinstance(params, dict) and agents+ else set()+ )+ for name in sorted(+ declared - used - read_by_conditions - used_by_params - applies_to_all+ ):+ warnings.append(+ Finding(+ "unused_param", f"Parameter '{name}' is declared but never used.", name+ )+ )++def lint_template(text: str) -> LintResult:"""Check a template document without storing or provisioning anything."""errors: list[Finding] = []@@ -261,6 +514,10 @@ def lint_template(text: str) -> LintResult:)return LintResult(errors, warnings)+ if is_v2(document):+ _lint_v2(document, errors, warnings)+ return LintResult(errors, warnings)+for key in sorted(k for k in document if isinstance(k, str)):if key not in _KNOWN_TOP_LEVEL:warnings.append(@@ -301,6 +558,8 @@ def lint_template(text: str) -> LintResult:))+ _check_agent_runtime(document, warnings)+# Placeholders are looked for everywhere except the params block, which# declares them rather than using them.body = {k: v for k, v in document.items() if k != "params"}@@ -316,6 +575,16 @@ def lint_template(text: str) -> LintResult:# Whether `$creator` also came back from PLACEHOLDER_RE depends on this# server's version of it; either way it is a builtin, not a missing param.used -= builtins_used+ # Inside an entry of `agents:`, `{agent}` is that entry's own name, filled+ # in when it is created (`directory: "{$agents_dir}/{agent}"`). Only a use+ # outside the entries needs the single `agent:` form to mean something.+ if isinstance(document.get("agents"), list) and "agent" not in declared:+ outside = {k: v for k, v in body.items() if k != "agents"}+ if not any(+ "agent" in re.findall(PLACEHOLDER_RE, text_node)+ for text_node in _walk_strings(outside)+ ):+ used.discard("agent")# `{$...}` is the server's to fill, not the template's to declare, so it is# held to a different question: is it one the server actually knows?@@ -330,17 +599,35 @@ def lint_template(text: str) -> LintResult:)for name in sorted(used - declared):+ team_agent = name == "agent" and isinstance(document.get("agents"), list)warnings.append(Finding("undeclared_placeholder",- f"'{{{name}}}' is used but no parameter declares it, so it will "- "be left in the document as written.",+ "'{agent}' outside an agent's own entry is ambiguous in a "+ "template with an agents: list, since it could be any of them. "+ "Name the agent by the text written as its name, or use the "+ "single agent: form, so it is not left in the document as written."+ if team_agent+ else f"'{{{name}}}' is used but no parameter declares it, so it "+ "will be left in the document as written.",name,))# `agent` is the Console's to fill, not a declared param, so a room that- # never names the agent is not an unused parameter.- for name in sorted(declared - used - {"agent"}):+ # never names the agent is not an unused parameter. Nor is a provider,+ # location or directory param in a document with agents: one no agent's+ # field reads applies to every agent.+ applies_to_all = (+ {+ name+ for name, spec in document["params"].items()+ if isinstance(spec, dict) and spec.get("type") in _RUNTIME_FIELDS+ }+ if ("agent" in document or "agents" in document)+ and isinstance(document.get("params"), dict)+ else set()+ )+ for name in sorted(declared - used - {"agent"} - applies_to_all):warnings.append(Finding("unused_param",diff --git a/core/switch_core/template_runs.py b/core/switch_core/template_runs.pynew file mode 100644index 000000000..2a1d61f0d--- /dev/null+++ b/core/switch_core/template_runs.py@@ -0,0 +1,629 @@+"""Creating the agents a template describes, whole or not at all.++A template that creates agents creates managed agents: Switch registers each+and places it on one of the owner's machines, whose controller runs it. A run+is checked whole before anything exists: every machine can take its agent+now, every name is free, every connection the agents are to be granted is+the owner's to grant. Only then are the agents created, one after another,+with their addressing and connections, and the rooms after them. When+anything fails past that point (a machine drops between the check and the+create, a room cannot be made), the agents the run created are deleted again,+and the refusal says so.++Switch Console and an agent running a saved template both come through here,+with the agents already resolved to what each is (`NewAgentPlan`): the+Console from its form, the server from the document (`agent_templates`).+"""++from __future__ import annotations++import asyncio+import logging+from collections.abc import Sequence+from dataclasses import dataclass, field, replace+from typing import TYPE_CHECKING, Any, Literal++from switch_core.addressing import AddressingRule, owner_only_policy+from switch_core.agent_refusals import AgentRefused+from switch_core.authz import Principal, can+from switch_core.bridges.agent.protocol.agent_core import VALID_AGENT_NAME_RE+from switch_core.bridges.agent.protocol.agent_detail import addressing_policy_for+from switch_core.bridges.agent.protocol.agent_management import (+ AgentManagementPort,+ AgentManagementRefused,+ CheckedPlacement,+ NewManagedAgent,+)+from switch_core.connections.broker import CheckedGrant, ServiceBroker, ServiceError+from switch_core.db.models import Agent+from switch_core.db.session_scope import tenant_session++if TYPE_CHECKING:+ from switch_core.bridges.agent.protocol.agent_core import AgentCore++logger = logging.getLogger(__name__)++AGENTS_DIR = "{$agents_dir}"++# How long a run waits, in all, for the clients of the agents it created to+# be taking events before it makes their rooms.+LISTEN_TIMEOUT_SECONDS = 30.0+_CLIENT_POLL_SECONDS = 0.1++# How a template says who may address an agent, and the addressing choice+# each stands for.+TEMPLATE_ADDRESSING = {+ "owner": "owner_only",+ "owner-agents": "owner_and_owner_agents",+ "anyone": "anyone",+}+++@dataclass(frozen=True)+class ConnectionPlan:+ """A connection an agent is to be granted: the owner's own connection to+ `service`. `repositories` (`owner/name`) is what a GitHub grant reaches;+ `access` is None for the level a new grant takes by default."""++ service: str+ access: Literal["read", "write"] | None+ repositories: list[str]+++@dataclass(frozen=True)+class NewAgentPlan:+ """One agent a run creates, with every field resolved.++ `slot` is how the template names it, for messages. `machine` is the id or+ exact name of one of the owner's machines. `directory` may start with+ `{$agents_dir}`, the directory the machine keeps agents' workspaces in;+ None is the machine's own workspace for the agent. `addressing` is a+ template's word for it (`owner`, `owner-agents`, `anyone`).+ """++ slot: str+ name: str+ description: str+ display_name: str | None+ instructions: str+ provider: str+ machine: str+ model: str | None+ advanced_config: dict[str, Any]+ isolation: str+ auto_approve: bool+ directory: str | None+ addressing: str+ connections: list[ConnectionPlan] = field(default_factory=list)+ # Rooms that already exist, by name, the agent is added to once created.+ joins: list[str] = field(default_factory=list)+++@dataclass(frozen=True)+class Problem:+ """Why one agent of the run cannot be created: its slot, a reason code+ (management's, the connection broker's, or this module's) and a sentence+ to relay."""++ slot: str+ code: str+ message: str++ def as_dict(self) -> dict[str, str]:+ return {"slot": self.slot, "code": self.code, "message": self.message}+++class AgentsNotCreated(AgentRefused):+ """The run was refused before anything was created. `problems` lists+ every reason found, not just the first."""++ def __init__(self, problems: Sequence[Problem]) -> None:+ listed = "; ".join(f"{p.slot}: {p.message} ({p.code})" for p in problems)+ super().__init__("agents_not_created", f"Nothing was created. {listed}")+ self.problems = list(problems)+++class RunUndone(AgentRefused):+ """Something failed after agents were created; they were deleted again.+ `left_behind` names any that could not be."""++ def __init__(self, message: str, left_behind: list[str]) -> None:+ super().__init__("run_undone", message)+ self.left_behind = left_behind+++@dataclass(frozen=True)+class CheckedAgent:+ plan: NewAgentPlan+ placement: CheckedPlacement+ directory: str | None+ addressing_policy: dict[str, Any] | None+ grants: list[CheckedGrant]+ join_room_ids: list[str]+++@dataclass(frozen=True)+class CreatedAgent:+ slot: str+ agent_id: str+ name: str+ machine: dict[str, str]+ # Its client was taking events before the rooms were made, so a kickoff+ # posted into them reaches it. False when it had not started in time.+ listening: bool+++def _directory(+ plan: NewAgentPlan, placement: CheckedPlacement+) -> tuple[str | None, Problem | None]:+ """The directory to define the agent with: None for the machine's own+ workspace for it, a path otherwise."""+ if plan.directory is None or plan.directory == f"{AGENTS_DIR}/{plan.name}":+ return None, None+ if AGENTS_DIR not in plan.directory:+ return plan.directory, None+ if placement.workspaces_dir is None:+ return None, Problem(+ plan.slot,+ "directory_unknown",+ f"its directory starts with {AGENTS_DIR}, and machine "+ f"'{placement.machine_name}' has not reported where it keeps agents. "+ "Bring it online once, or give the directory as a full path.",+ )+ root = placement.workspaces_dir.rstrip("/\\")+ return plan.directory.replace(AGENTS_DIR, root), None+++def pending_addressing(+ plans: Sequence[NewAgentPlan],+ owner_id: str,+ room_addressing: dict[str, list[str]],+) -> dict[str, tuple[dict[str, Any] | None, str]]:+ """Each agent the run would create, by name, with the addressing policy+ it would have and its owner: what the kickoff check reads for an agent+ that does not exist yet. An agent opened to the rooms the run creates is+ read as open: its kickoff is posted in one of them, and those rooms have+ no id yet to scope a rule to."""+ return {+ plan.name: (+ None+ if room_addressing.get(plan.name)+ else addressing_policy_for(TEMPLATE_ADDRESSING[plan.addressing]),+ owner_id,+ )+ for plan in plans+ if plan.addressing in TEMPLATE_ADDRESSING+ }+++def room_ids_of(result: dict[str, Any]) -> dict[str, str]:+ """The rooms a provisioning made, by name: one room's result or a+ group's."""+ if "rooms" in result:+ return {r["room_name"]: r["room_id"] for r in result["rooms"]}+ return {result["room_name"]: result["room_id"]}+++class TemplateAgents:+ """Checks, creates and, when the run fails, deletes a run's agents, for+ one owner in one tenant."""++ def __init__(+ self,+ *,+ protocol: AgentCore,+ management: AgentManagementPort | None,+ broker: ServiceBroker | None,+ listen_timeout: float,+ ) -> None:+ self._protocol = protocol+ self._management = management+ self._broker = broker+ self._listen_timeout = listen_timeout++ async def check(+ self, tenant_id: str, owner_id: str, plans: Sequence[NewAgentPlan]+ ) -> list[CheckedAgent]:+ """Every agent checked, with nothing created; refused with every+ problem found when any is."""+ if not plans:+ return []+ if self._management is None:+ raise AgentsNotCreated(+ [+ Problem(+ plan.slot,+ "agent_management_off",+ "agent management is not enabled on this Switch server, "+ "so it cannot create agents on a machine.",+ )+ for plan in plans+ ]+ )+ problems: list[Problem] = []+ names = [plan.name for plan in plans]+ async with tenant_session(self._protocol.session_factory, tenant_id) as session:+ taken = {+ agent.name+ for agent in await self._protocol.agent_store.get_by_names(+ session, names+ )+ }+ seen: set[str] = set()+ checked: list[CheckedAgent] = []+ for plan in plans:+ if not VALID_AGENT_NAME_RE.match(plan.name):+ problems.append(+ Problem(+ plan.slot,+ "invalid_name",+ f"'{plan.name}' is not an agent name: use lowercase "+ "letters, digits, '.', '-' and '_', starting with a "+ "letter or digit.",+ )+ )+ continue+ if plan.name in seen:+ problems.append(+ Problem(+ plan.slot,+ "name_repeated",+ f"the template creates two agents named '{plan.name}'.",+ )+ )+ continue+ seen.add(plan.name)+ if plan.name in taken:+ problems.append(+ Problem(+ plan.slot,+ "name_taken",+ f"an agent named '{plan.name}' already exists. Choose "+ "another name; nothing is renamed for you.",+ )+ )+ continue+ if plan.addressing not in TEMPLATE_ADDRESSING:+ problems.append(+ Problem(+ plan.slot,+ "invalid_addressing",+ f"addressing '{plan.addressing}' is not one of "+ f"{', '.join(TEMPLATE_ADDRESSING)}.",+ )+ )+ continue+ try:+ placement = await self._management.check_new_agent(+ tenant_id, owner_id, self._spec(plan, plan.machine, plan.directory)+ )+ except AgentManagementRefused as refused:+ problems.append(+ Problem(plan.slot, refused.code, _bare(str(refused), refused.code))+ )+ continue+ directory, problem = _directory(plan, placement)+ if problem is not None:+ problems.append(problem)+ continue+ grants, grant_problems = await self._check_grants(tenant_id, owner_id, plan)+ problems.extend(grant_problems)+ join_room_ids, join_problems = await self._check_joins(+ tenant_id, owner_id, plan+ )+ problems.extend(join_problems)+ checked.append(+ CheckedAgent(+ plan=plan,+ placement=placement,+ directory=directory,+ addressing_policy=addressing_policy_for(+ TEMPLATE_ADDRESSING[plan.addressing]+ ),+ grants=grants,+ join_room_ids=join_room_ids,+ )+ )+ if problems:+ raise AgentsNotCreated(problems)+ return checked++ async def _check_joins(+ self, tenant_id: str, owner_id: str, plan: NewAgentPlan+ ) -> tuple[list[str], list[Problem]]:+ """The rooms the agent joins, by id: each must exist, be one the owner+ sees, and one the owner may add agents to."""+ if not plan.joins:+ return [], []+ async with tenant_session(self._protocol.session_factory, tenant_id) as session:+ readable = await self._protocol.room_store.list_readable(+ session, owner_id, is_admin=False+ )+ ids: list[str] = []+ problems: list[Problem] = []+ for name in plan.joins:+ matches = [room for room in readable if room.name == name]+ if not matches:+ problems.append(+ Problem(+ plan.slot,+ "join_unknown_room",+ f"it joins {name}, and no room of that name is one you can see.",+ )+ )+ elif len(matches) > 1:+ problems.append(+ Problem(+ plan.slot,+ "join_ambiguous_room",+ f"it joins {name}, and {len(matches)} rooms have that name.",+ )+ )+ elif not can(Principal(owner_id, False), "write", matches[0]):+ problems.append(+ Problem(+ plan.slot,+ "join_not_allowed",+ f"it joins {name}, and you may not add agents to that room.",+ )+ )+ else:+ ids.append(matches[0].id)+ return ids, problems++ async def _check_grants(+ self, tenant_id: str, owner_id: str, plan: NewAgentPlan+ ) -> tuple[list[CheckedGrant], list[Problem]]:+ if not plan.connections:+ return [], []+ if self._broker is None:+ return [], [+ Problem(+ plan.slot,+ "connections_off",+ "connections are not enabled on this Switch server, so it "+ f"cannot be granted {', '.join(c.service for c in plan.connections)}.",+ )+ ]+ grants: list[CheckedGrant] = []+ problems: list[Problem] = []+ services = [c.service for c in plan.connections]+ for repeated in sorted({s for s in services if services.count(s) > 1}):+ problems.append(+ Problem(+ plan.slot,+ "connection_repeated",+ f"it lists {repeated} twice; an agent has one grant per service.",+ )+ )+ for connection in plan.connections:+ unavailable = self._broker.availability(connection.service)+ if unavailable is not None:+ problems.append(+ Problem(+ plan.slot,+ "connection_unavailable",+ f"{connection.service}: {unavailable}",+ )+ )+ continue+ async with tenant_session(+ self._protocol.session_factory, tenant_id+ ) as session:+ try:+ grants.append(+ await self._broker.check_grant_terms(+ session,+ owner_id=owner_id,+ service=connection.service,+ access=connection.access,+ repositories=connection.repositories,+ )+ )+ except ServiceError as error:+ problems.append(+ Problem(+ plan.slot,+ error.code,+ f"{connection.service}: {error.message}",+ )+ )+ return grants, problems++ @staticmethod+ def _spec(+ plan: NewAgentPlan, machine: str, directory: str | None+ ) -> NewManagedAgent:+ return NewManagedAgent(+ name=plan.name,+ description=plan.description,+ display_name=plan.display_name,+ icon_url=None,+ machine=machine,+ provider=plan.provider,+ model=plan.model,+ advanced_config=plan.advanced_config,+ instructions=plan.instructions,+ directory=directory,+ auto_approve=plan.auto_approve,+ isolation=plan.isolation,+ start=True,+ )++ async def create(+ self, tenant_id: str, owner_id: str, checked: Sequence[CheckedAgent]+ ) -> list[CreatedAgent]:+ """Create the checked agents with their addressing and connections.+ When one fails, the ones already created are deleted again and the+ failure is raised as `RunUndone`."""+ if not checked:+ return []+ assert self._management is not None+ created: list[CreatedAgent] = []+ for agent in checked:+ plan = agent.plan+ try:+ result = await self._management.create_agent(+ tenant_id,+ owner_id,+ self._spec(plan, agent.placement.machine_id, agent.directory),+ self._protocol,+ )+ created.append(+ CreatedAgent(+ slot=plan.slot,+ agent_id=result["agent_id"],+ name=result["name"],+ machine=dict(result["machine"]),+ listening=False,+ )+ )+ await self._finish(tenant_id, owner_id, result["agent_id"], agent)+ for room_id in agent.join_room_ids:+ await self._protocol.room_service.add_agents_to_room(+ room_id, agent_ids=[result["agent_id"]]+ )+ except Exception as error:+ raise await self.undone(+ created, f"creating {plan.name} failed: {_reason(error)}"+ ) from error+ return await self._listening(created)++ async def _listening(self, created: list[CreatedAgent]) -> list[CreatedAgent]:+ """Wait, up to the listen timeout in all, for each new agent's client+ to be taking events. A client that starts after a room exists reads+ it only from then on, so without this the kickoff posted the moment+ the room is made never reaches an agent created a moment before."""+ loop = asyncio.get_running_loop()+ deadline = loop.time() + self._listen_timeout+ out: list[CreatedAgent] = []+ for agent in created:+ actor = self._protocol.client_lifecycle.get_by_agent_id(agent.agent_id)+ while actor is None and loop.time() < deadline:+ await asyncio.sleep(_CLIENT_POLL_SECONDS)+ actor = self._protocol.client_lifecycle.get_by_agent_id(agent.agent_id)+ listening = actor is not None and await actor.wait_receiving(+ max(0.0, deadline - loop.time())+ )+ if not listening:+ logger.warning(+ "New agent %s (%s) was not taking events within %ss of being "+ "created; a kickoff posted now may not reach it",+ agent.name,+ agent.agent_id,+ self._listen_timeout,+ )+ out.append(replace(agent, listening=listening))+ return out++ async def _finish(+ self, tenant_id: str, owner_id: str, agent_id: str, agent: CheckedAgent+ ) -> None:+ """Set what creating the managed agent does not: who may address it+ and the connections it is granted."""+ async with tenant_session(self._protocol.session_factory, tenant_id) as session:+ await self._protocol.agent_store.update(+ session, agent_id, addressing_policy=agent.addressing_policy+ )+ await session.commit()+ if not agent.grants:+ return+ assert self._broker is not None+ for grant in agent.grants:+ async with tenant_session(+ self._protocol.session_factory, tenant_id+ ) as session:+ row = await session.get(Agent, agent_id)+ if row is None:+ raise RuntimeError(f"agent {agent_id} vanished while being created")+ _, warning = await self._broker.set_grant(+ session,+ agent=row,+ actor_id=owner_id,+ service=grant.service,+ access=grant.access,+ tool_mode=None,+ tools=None,+ resources=grant.resources,+ )+ if warning:+ logger.warning(+ "Granting %s to new agent %s: %s",+ grant.service,+ agent_id,+ warning,+ )++ async def open_to_rooms(+ self,+ tenant_id: str,+ created: Sequence[CreatedAgent],+ room_addressing: dict[str, list[str]],+ room_ids: dict[str, str],+ ) -> None:+ """Let anyone in the named rooms address the agents opened to them,+ once those rooms exist, on top of their owner."""+ for agent in created:+ rooms = room_addressing.get(agent.name)+ if not rooms:+ continue+ missing = [r for r in rooms if r not in room_ids]+ if missing:+ raise RuntimeError(+ f"{agent.name} is opened to {', '.join(missing)}, which "+ "the run did not create"+ )+ policy = owner_only_policy([])+ policy.rules.append(AddressingRule(rooms=[room_ids[r] for r in rooms]))+ async with tenant_session(+ self._protocol.session_factory, tenant_id+ ) as session:+ await self._protocol.agent_store.update(+ session, agent.agent_id, addressing_policy=policy.model_dump()+ )+ await session.commit()++ async def undone(self, created: Sequence[CreatedAgent], what: str) -> RunUndone:+ """Delete the agents a run created, and the refusal saying so. An+ agent that cannot be deleted is named, never passed over."""+ left_behind: list[str] = []+ for agent in reversed(created):+ try:+ await self._protocol.delete_agent(agent_id=agent.agent_id)+ except Exception:+ logger.exception(+ "Could not delete agent %s (%s) while undoing a template run",+ agent.name,+ agent.agent_id,+ )+ left_behind.append(agent.name)+ removed = [a.name for a in created if a.name not in left_behind]+ message = f"Nothing was kept: {what}."+ if removed:+ message += (+ f" The agents this run had created ({', '.join(removed)}) were deleted."+ )+ if left_behind:+ message += (+ f" {', '.join(left_behind)} could not be deleted and still "+ "exist; delete them in Switch Console."+ )+ return RunUndone(message, left_behind)+++def _bare(message: str, code: str) -> str:+ """Management's sentence without what the run's own refusal says around+ it: its "Nothing was created:" opening and its trailing reason code."""+ for opening in ("Nothing was created: ", "Nothing was created. "):+ if message.startswith(opening):+ message = message[len(opening) :]+ for ending in (f" ({code}).", f" ({code})"):+ if message.endswith(ending):+ message = message[: -len(ending)]+ return message.rstrip(".")+++def _reason(error: Exception) -> str:+ if isinstance(error, ServiceError):+ return error.message+ return str(error) or type(error).__name__diff --git a/core/switch_core/template_v2.py b/core/switch_core/template_v2.pynew file mode 100644index 000000000..20a4c4ea1--- /dev/null+++ b/core/switch_core/template_v2.py@@ -0,0 +1,400 @@+"""Version 2 of the template language: resources with a key and a type.++A version 1 document says what a block is by where it sits (``agent:``,+``agents:``, ``room:``, ``group:`` with ``rooms:``) and links them by+matching text: a room lists ``"{team}-lead"`` and the agent whose name reads+the same is the one meant. Version 2 says it outright::++ version: 2+ params:+ start_in: { type: enum, enum: [nowhere, new_room], default: nowhere }+ resources:+ expert:+ type: agent+ display_name: Switch expert+ machine: "{machine}"+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ agents: [expert]+ kickoff: "@{expert.name} hi"++Every resource has a key and a ``type`` (``agent``, ``room``, ``group``).+Resources refer to each other by key: ``agents: [expert]`` on a room, and+``{expert.name}`` anywhere for the name a resource is created under. One+construct is conditional, ``if:``: on a resource (it is created only when the+condition holds), on a param (asked only when it holds), and in a field's+value written as a list of ``{if, value}``, the first that holds being taken.+A condition is ``"{param}"`` (true when the value is) or ``"{param} == x"`` /+``"{param} != x"``.++A version 2 document is compiled, once the inputs are known, into the+version 1 document it amounts to, which the rest of the template engine runs+as it always has. What version 1 cannot say comes back beside it: an agent+whose addressing admits anyone in one of the rooms the run creates.+"""++from __future__ import annotations++import re+from dataclasses import dataclass, field+from typing import Any++import yaml++from switch_core.rooms_yaml import PLACEHOLDER_RE, ParamSpec, coerce_param, interpolate++RESOURCE_TYPES = ("agent", "room", "group")++# A reference to the name a resource is created under.+_NAME_REF = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\.name\}")+_CONDITION = re.compile(+ r"\A\s*\{([A-Za-z_][A-Za-z0-9_]*)\}\s*(?:(==|!=)\s*(.*?))?\s*\Z"+)+# Past this a display name is not slugged, as in the Console's agent-slug.+_MAX_SLUG_INPUT = 128++_AGENT_ONLY = ("type", "if")+_ROOM_ONLY = ("type", "if", "kickoff", "group")+_GROUP_ONLY = ("type", "if", "links")+++class TemplateError(ValueError):+ """A version 2 document that cannot be compiled, saying where."""+++def is_v2(data: dict[str, Any]) -> bool:+ return data.get("version") == 2 or "resources" in data+++def is_v2_text(text: str) -> bool:+ """Whether a document's text is version 2; false for one that does not+ parse, which the version 1 path reports."""+ try:+ data = yaml.safe_load(text)+ except yaml.YAMLError:+ return False+ return isinstance(data, dict) and is_v2(data)+++def _slug(value: str) -> str:+ if len(value) > _MAX_SLUG_INPUT:+ return ""+ slug = re.sub(r"[^a-z0-9._]+", "-", value.lower())+ return re.sub(r"^[._-]+|[._-]+$", "", slug)+++def condition_params(expression: str) -> str:+ """The param a condition reads; raises for one that is not a condition."""+ match = _CONDITION.match(str(expression))+ if match is None:+ raise TemplateError(+ f"'{expression}' is not a condition: write \"{{param}}\", "+ '"{param} == value" or "{param} != value".'+ )+ return match.group(1)+++def holds(expression: Any, values: dict[str, Any]) -> bool:+ """Whether a condition holds with these values. A param with no value+ is false, and equal to nothing."""+ match = _CONDITION.match(str(expression))+ if match is None:+ raise TemplateError(+ f"'{expression}' is not a condition: write \"{{param}}\", "+ '"{param} == value" or "{param} != value".'+ )+ name, op, literal = match.groups()+ value = values.get(name)+ if op is None:+ return value not in (None, "", False, 0)+ equal = value is not None and str(value) == str(literal).strip().strip("'\"")+ return equal if op == "==" else not equal+++def _choose(node: Any, values: dict[str, Any]) -> Any:+ """A field written as ``[{if, value}, ...]`` becomes the first value whose+ condition holds (an entry with no ``if`` always does); every other node+ is walked as it is."""+ if (+ isinstance(node, list)+ and node+ and all(isinstance(item, dict) and "value" in item for item in node)+ ):+ for item in node:+ if "if" not in item or holds(item["if"], values):+ return _choose(item["value"], values)+ return None+ if isinstance(node, dict):+ return {k: _choose(v, values) for k, v in node.items()}+ if isinstance(node, list):+ return [_choose(item, values) for item in node]+ return node+++def _drop_empty(node: Any) -> Any:+ if isinstance(node, dict):+ return {k: _drop_empty(v) for k, v in node.items()}+ if isinstance(node, list):+ return [_drop_empty(item) for item in node if item != ""]+ return node+++def _known_values(+ params: dict[str, dict[str, Any]],+ inputs: dict[str, Any],+ builtins: dict[str, str],+) -> dict[str, Any]:+ """Each given input, else each plain default, checked as the server+ checks them; a chain or a value nobody gave is left unknown."""+ values: dict[str, Any] = dict(builtins)+ for name, raw in params.items():+ spec = ParamSpec.model_validate({k: v for k, v in raw.items() if k != "if"})+ if inputs.get(name) not in (None, ""):+ values[name] = coerce_param(inputs[name], spec, name)+ elif spec.default is not None and not isinstance(spec.default, list):+ values[name] = coerce_param(spec.default, spec, name)+ return values+++@dataclass(frozen=True)+class Compiled:+ """A version 2 document as the version 1 document it amounts to, the+ inputs to run it with, and, per agent created, the rooms (by name) whose+ members may address it beyond its owner."""++ document: str+ inputs: dict[str, Any]+ room_addressing: dict[str, list[str]] = field(default_factory=dict)+ # Each resource's key, with the name it is created under.+ names: dict[str, str] = field(default_factory=dict)+++def _resources(data: dict[str, Any]) -> dict[str, dict[str, Any]]:+ raw = data.get("resources")+ if not isinstance(raw, dict) or not raw:+ raise TemplateError("'resources' must map each resource's key to it.")+ out: dict[str, dict[str, Any]] = {}+ for key, spec in raw.items():+ if not isinstance(spec, dict):+ raise TemplateError(f"resource '{key}' must be a mapping.")+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", str(key)):+ raise TemplateError(+ f"resource key '{key}' must be letters, digits and _, so "+ "{key.name} can name it."+ )+ if spec.get("type") not in RESOURCE_TYPES:+ raise TemplateError(+ f"resource '{key}' needs a type: one of {', '.join(RESOURCE_TYPES)}."+ )+ out[str(key)] = spec+ return out+++def compile_v2(text: str, inputs: dict[str, Any], builtins: dict[str, str]) -> Compiled:+ data = yaml.safe_load(text)+ if not isinstance(data, dict):+ raise TemplateError("A template is a YAML mapping.")+ raw_params = data.get("params") or {}+ if not isinstance(raw_params, dict):+ raise TemplateError("'params' must map each param's name to its spec.")+ params = {k: dict(v) for k, v in raw_params.items() if isinstance(v, dict)}+ undeclared = set(inputs) - set(params)+ if undeclared:+ raise TemplateError(f"Undeclared input(s): {', '.join(sorted(undeclared))}")+ values = _known_values(params, inputs, builtins)++ # A param whose condition does not hold is not asked, and not used.+ off: dict[str, Any] = {}+ for name, spec in list(params.items()):+ if "if" in spec and not holds(spec["if"], values):+ del params[name]+ values.pop(name, None)+ off[name] = ""+ resources = {+ key: spec+ for key, spec in _resources(data).items()+ if "if" not in spec or holds(spec["if"], values)+ }+ dropped = set(_resources(data)) - set(resources)+ # A param that is not asked reads as empty, and drops out of the lists it+ # was written in (a `join` with no room picked joins nothing).+ resources = {+ key: _drop_empty(interpolate(_choose(spec, values), off))+ for key, spec in resources.items()+ }++ names: dict[str, str] = {}++ def name_of(key: str, spec: dict[str, Any]) -> str:+ if spec["type"] == "agent":+ written = spec.get("name") or ""+ name = (+ str(interpolate(str(written), values))+ if written+ else _slug(+ str(interpolate(str(spec.get("display_name") or ""), values))+ )+ )+ else:+ name = str(interpolate(str(spec.get("name") or ""), values))+ if not name or PLACEHOLDER_RE.search(name) or _NAME_REF.search(name):+ raise TemplateError(+ f"resource '{key}' has no name yet: give it a 'name' (or, for an "+ "agent, a 'display_name') whose inputs have values."+ )+ return name++ def resolve(node: Any, where: str) -> Any:+ if isinstance(node, str):++ def by_key(match: re.Match[str]) -> str:+ key = match.group(1)+ if key in names:+ return names[key]+ if key in dropped:+ raise TemplateError(+ f"{where} refers to {key}, which this run does not "+ "create (its 'if' does not hold)."+ )+ return match.group(0)++ return _NAME_REF.sub(by_key, node)+ if isinstance(node, dict):+ return {resolve(k, where): resolve(v, where) for k, v in node.items()}+ if isinstance(node, list):+ return [resolve(item, where) for item in node]+ return node++ # Agents first: a room's name may read an agent's, never the reverse.+ for key, spec in resources.items():+ if spec["type"] == "agent":+ names[key] = name_of(key, spec)+ resources = {key: resolve(spec, key) for key, spec in resources.items()}+ for key, spec in resources.items():+ if spec["type"] != "agent":+ names[key] = name_of(key, spec)+ resources = {key: resolve(spec, key) for key, spec in resources.items()}+ agent_keys = {k for k, s in resources.items() if s["type"] == "agent"}+ room_keys = [k for k, s in resources.items() if s["type"] == "room"]+ group_keys = [k for k, s in resources.items() if s["type"] == "group"]++ def agent_name(item: Any, where: str) -> Any:+ if isinstance(item, str) and item in agent_keys:+ return names[item]+ if isinstance(item, str) and item in dropped:+ raise TemplateError(+ f"{where} lists {item}, which this run does not create (its "+ "'if' does not hold)."+ )+ return item++ room_addressing: dict[str, list[str]] = {}+ agents: list[dict[str, Any]] = []+ for key in agent_keys:+ spec = resources[key]+ entry = {k: v for k, v in spec.items() if k not in _AGENT_ONLY}+ entry["name"] = names[key]+ addressing = entry.get("addressing")+ if isinstance(addressing, dict):+ rooms = addressing.get("anyone_in")+ if set(addressing) != {"anyone_in"} or not isinstance(rooms, list):+ raise TemplateError(+ f"{key}: addressing is owner, owner-agents, anyone, or "+ "{anyone_in: [room keys]}."+ )+ unknown = [r for r in rooms if r not in room_keys]+ if unknown:+ raise TemplateError(+ f"{key}: addressing anyone_in names {', '.join(map(str, unknown))}, "+ "which this run does not create as a room."+ )+ room_addressing[names[key]] = [names[r] for r in rooms]+ entry["addressing"] = "owner"+ for join in entry.get("join") or []:+ if isinstance(join, str) and join in room_keys:+ raise TemplateError(+ f"{key}: join names {join}, a room this template creates; list "+ f"the agent in that room's agents instead."+ )+ agents.append(entry)++ def room_block(key: str) -> dict[str, Any]:+ spec = resources[key]+ room = {k: v for k, v in spec.items() if k not in _ROOM_ONLY}+ room["name"] = names[key]+ if isinstance(room.get("agents"), list):+ room["agents"] = [agent_name(a, key) for a in room["agents"]]+ if isinstance(room.get("aliases"), dict):+ room["aliases"] = {+ agent_name(k, key): v for k, v in room["aliases"].items()+ }+ return room++ out: dict[str, Any] = {"version": 1}+ kept_params = {+ k: resolve({kk: vv for kk, vv in v.items() if kk != "if"}, f"param {k}")+ for k, v in params.items()+ }+ if kept_params:+ out["params"] = kept_params+ if agents:+ out["agents"] = agents+ if len(group_keys) > 1:+ raise TemplateError("A template creates at most one group.")+ if group_keys:+ group = resources[group_keys[0]]+ out["group"] = {k: v for k, v in group.items() if k not in _GROUP_ONLY}+ out["group"]["name"] = names[group_keys[0]]+ rooms = []+ for key in room_keys:+ if resources[key].get("group") not in (None, group_keys[0]):+ raise TemplateError(+ f"{key}: group names a group this template does not create."+ )+ block = room_block(key)+ if resources[key].get("kickoff"):+ block["kickoff"] = resources[key]["kickoff"]+ rooms.append(block)+ out["rooms"] = rooms+ links = []+ for link in group.get("links") or []:+ if not isinstance(link, dict):+ raise TemplateError(+ f"{group_keys[0]}: each link is {{from, to, label}}."+ )+ ends = [link.get("from"), link.get("to")]+ for end in ends:+ if end not in room_keys:+ raise TemplateError(+ f"{group_keys[0]}: a link names {end}, which is not a room "+ "this run creates."+ )+ links.append(+ {+ "from": names[str(ends[0])],+ "to": names[str(ends[1])],+ **({"label": link["label"]} if link.get("label") else {}),+ }+ )+ if links:+ out["links"] = links+ elif len(room_keys) > 1:+ raise TemplateError(+ "Several rooms go in a group: add a resource of type group, and give "+ "each room group: <its key>."+ )+ elif room_keys:+ out["room"] = room_block(room_keys[0])+ if resources[room_keys[0]].get("kickoff"):+ out["kickoff"] = resources[room_keys[0]]["kickoff"]+ # An input may carry a reference too: a directory param's default,+ # "{$agents_dir}/{expert.name}", filled into the form and sent back.+ run_inputs = {k: resolve(v, f"input {k}") for k, v in inputs.items() if k in params}+ return Compiled(+ document=yaml.safe_dump(out, sort_keys=False, allow_unicode=True),+ inputs=run_inputs,+ room_addressing=room_addressing,+ names=names,+ )diff --git a/core/switch_core/transport/port.py b/core/switch_core/transport/port.pyindex a1e5be81c..777b8a010 100644--- a/core/switch_core/transport/port.py+++ b/core/switch_core/transport/port.py@@ -69,6 +69,11 @@ class MessageTransport(Protocol):"""Deliver inbound events to the registered handlers until closed."""...+ async def wait_receiving(self, timeout: float) -> bool:+ """Block until `receive_forever` is taking events and will hear an+ invite to a new room, up to `timeout` seconds. False on timeout."""+ ...+# ── Outbound ──────────────────────────────────────────────────────────────async def send_message(diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.pyindex 5c7111427..2fcfd671a 100644--- a/core/switch_core/transport/postgres.py+++ b/core/switch_core/transport/postgres.py@@ -229,6 +229,7 @@ class PostgresTransport:self._cursors: dict[str, int] = {}self._watching: dict[str, str] = {}self._receiving = False+ self._receiving_event = asyncio.Event()self._closed = asyncio.Event()# Rooms this client has been told moved but has not read yet, and the# signal its delivery loop waits on. A set because a room that moved@@ -265,6 +266,7 @@ class PostgresTransport:# during those has no membership row for the caller to fall back to.self._invites.register(self.client_id, self._on_invited, self._on_removed)self._receiving = True+ self._receiving_event.set()try:rooms = await self.joined_rooms()if not rooms:@@ -283,9 +285,17 @@ class PostgresTransport:delivery.cancel()finally:self._receiving = False+ self._receiving_event.clear()self._invites.unregister(self.client_id, self._on_invited, self._on_removed)self._unwatch_all()+ async def wait_receiving(self, timeout: float) -> bool:+ try:+ await asyncio.wait_for(self._receiving_event.wait(), timeout)+ except TimeoutError:+ return False+ return True+async def _deliver_forever(self) -> None:"""This client's own delivery loop: its rooms, one at a time.diff --git a/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py b/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.pyindex 31a90bdfd..898cd6c99 100644--- a/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py+++ b/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py@@ -18,7 +18,12 @@ from sqlalchemy import select, updatefrom switch_core.agent_refusals import AgentRefusedfrom switch_core.agent_template_ops import ActingFor, AgentTemplates-from switch_core.agent_templates import agent_slots, room_document, template_kind+from switch_core.agent_templates import (+ agent_slots,+ plan_template,+ room_document,+ template_kind,+)from switch_core.bridges.agent.operations.callctx import (CallContext,reset_call_context,@@ -58,9 +63,11 @@ agents:description: Routes reportsprovider: "{provider}"instructions: Route reports.+ allow_existing: true- name: "{team}-repro"description: Reproduces bugsinstructions: Reproduce bugs.+ allow_existing: trueroom:name: "{team}-triage"description: The triage room@@ -74,6 +81,7 @@ agent:name: jq-expertdescription: Answers jq questionsinstructions: Answer jq questions.+ allow_existing: trueroom:name: "Ask {agent}"description: "Ask {agent} about jq"@@ -84,7 +92,9 @@ kickoff: "@{agent} introduce yourself."@pytest_asyncio.fixtureasync def tools(env):- env["protocol"].config = SimpleNamespace(template_max_bytes=64 * 1024)+ env["protocol"].config = SimpleNamespace(+ template_max_bytes=64 * 1024, feature_flags={"agent_management": False}+ )env["protocol"].telemetry = Noneasync with env["session_factory"]() as session:stranger = User(name="mallory", email="[email protected]", role="member")@@ -128,6 +138,11 @@ async def _bob_id(env: dict[str, Any]) -> str:return bob.id+def _saved(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """A listing without the templates that come with Switch."""+ return [r for r in rows if r["saved_by"] != "Switch"]++@pytest.fixture(autouse=True)def _refusal_log(caplog: pytest.LogCaptureFixture) -> None:caplog.set_level(logging.INFO, logger="switch_core.agent_refusals")@@ -171,15 +186,18 @@ def test_a_team_template_becomes_a_room_with_the_chosen_agents():assert inputs == {}-def test_an_unfilled_slot_is_refused_with_the_console_message():- with pytest.raises(- AgentRefused, match="creating agents happens in Switch Console"- ) as e:- room_document(- TEAM_TEMPLATE, {"red-triager": "claude-code.alice"}, {"team": "red"}+def test_an_existing_agent_only_stands_in_where_the_template_allows_it():+ template = TEAM_TEMPLATE.replace(" allow_existing: true\n", "", 1)+ with pytest.raises(AgentRefused) as e:+ plan_template(+ template,+ {"red-triager": "claude-code.alice", "red-repro": "claude-code.bob"},+ {"team": "red"},+ builtins={},+ machines=None,)- assert e.value.reason == "agent_creation_console_only"- assert "red-repro" in str(e.value)+ assert e.value.reason == "agents_not_created"+ assert "red-triager: the template does not let an existing agent" in str(e.value)# ── The tools ─────────────────────────────────────────────────────────────@@ -205,9 +223,15 @@ async def test_list_shows_shared_and_the_owners_private_templates(tools):rows = await _as(tools["agent_id"], list_templates)- assert {r["name"] for r in rows} == {"mine-private", "theirs-shared"}+ # The ones that come with Switch first, then what the owner can read.+ assert rows[0]["id"] == "official:switch-expert"+ assert {r["name"] for r in rows} == {+ "Switch expert",+ "mine-private",+ "theirs-shared",+ }assert all(r["can_edit"] is False for r in rows)- assert {r["saved_by"] for r in rows} == {"alice", "mallory"}+ assert {r["saved_by"] for r in rows} == {"Switch", "alice", "mallory"}@pytest.mark.asyncio@@ -295,15 +319,20 @@ async def test_run_an_agent_template_with_an_existing_agent(tools):@pytest.mark.asyncio-async def test_run_that_would_create_an_agent_is_refused_and_reported(tools, caplog):+async def test_run_that_would_create_an_agent_without_management_is_refused(+ tools, caplog+):template_id = await _stored(tools, tools["user_id"], "jq", AGENT_TEMPLATE, kind="agent")- with pytest.raises(AgentRefused, match="Switch Console"):+ with pytest.raises(AgentRefused, match="Nothing was created") as e:await _as(tools["agent_id"], run_template, template_id=template_id)- assert _refusals(caplog) == [("run_template", "agent_creation_console_only")]+ # The entry never says where it runs, and this server has no agent+ # management to run it on: both are named, and nothing is created.+ assert "machine_unsaid" in str(e.value)+ assert _refusals(caplog) == [("run_template", "agents_not_created")]assert "Refused agent claude-code.alice" in caplog.text@@ -347,11 +376,53 @@ async def test_save_is_owned_by_the_owner_and_marked_with_the_agent(tools):)assert saved["kind"] == "room"rows = await _as(tools["agent_id"], list_templates)- assert [(r["name"], r["can_edit"], r["saved_by"]) for r in rows] == [+ assert [(r["name"], r["can_edit"], r["saved_by"]) for r in _saved(rows)] == [("standup", True, "agent claude-code.alice")]+async def test_save_refuses_a_template_with_warnings_unless_bypassed(tools, caplog):+ """An agent saving a template that never says what runs its agent is told+ so before anything is stored, and may save it anyway once it has seen it."""+ with pytest.raises(AgentRefused, match="which coding agent runs jq-expert") as e:+ await _as(+ tools["agent_id"],+ save_template,+ name="jq",+ description="jq expert",+ yaml=AGENT_TEMPLATE,+ )+ assert "bypass_warnings=true" in str(e.value)+ assert _refusals(caplog) == [("save_template", "has_warnings")]+ rows = await _as(tools["agent_id"], list_templates)+ assert _saved(rows) == [], "nothing is stored when refused"++ saved = await _as(+ tools["agent_id"],+ save_template,+ name="jq",+ description="jq expert",+ yaml=AGENT_TEMPLATE,+ bypass_warnings=True,+ )+ async with tools["session_factory"]() as session:+ assert await session.get(Template, saved["id"]) is not None+ assert any("which coding agent runs jq-expert" in w for w in saved["warnings"])++ with pytest.raises(AgentRefused, match="which coding agent runs jq-expert"):+ await _as(+ tools["agent_id"],+ update_template,+ template_id=saved["id"],+ yaml=AGENT_TEMPLATE,+ )+ updated = await _as(+ tools["agent_id"], update_template, template_id=saved["id"], description="x"+ )+ assert updated["warnings"] == [], "no document was passed, so none was checked"++@pytest.mark.asyncioasync def test_save_refuses_a_template_anyone_could_change(tools, caplog):with pytest.raises(AgentRefused, match="not one an agent can set"):@@ -441,8 +512,10 @@ params:agents:- name: "{team}-lead"instructions: Lead.+ allow_existing: true- name: "{team}-helper"instructions: Help.+ allow_existing: truegroup:name: "{team}"rooms:@@ -549,7 +622,9 @@ async def test_the_saver_check_holds_when_the_mark_is_cleared_after_reading(tooldescription="",yaml=ROOM_TEMPLATE,)- templates = AgentTemplates(TemplateStore(), max_bytes=64 * 1024)+ templates = AgentTemplates(+ TemplateStore(), max_bytes=64 * 1024, agent_management=False+ )async with tools["session_factory"]() as session:agent = await session.get(Agent, tools["agent_id"])owner = await session.get(User, tools["user_id"])@@ -578,6 +653,7 @@ async def test_the_saver_check_holds_when_the_mark_is_cleared_after_reading(tooldescription="changed",content=None,visibility=None,+ bypass_warnings=False,)@@ -658,9 +734,10 @@ async def test_the_guide_describes_the_language_and_the_example_in_it_is_valid(texample = (result["guide"].split("## Example\n\n", 1)[1]+ .split("\n## ", 1)[0].replace("[reviewer]", '["claude-code.alice"]').replace("@reviewer", "@claude-code.alice")- .replace(' users: ["{$creator}"]\n', "")+ .replace(' users: ["{$creator}"]\n', ""))created = await _as(tools["agent_id"],@@ -764,3 +841,26 @@ rooms:- { name: lobby, description: Lobby, agents: [lead] }"""assert template_kind(template) == "group"+++async def test_an_official_template_is_read_and_never_changed(tools, caplog):+ detail = await _as(+ tools["agent_id"], get_template, template_id="official:switch-expert"+ )+ # Without agent management, the document Switch Console runs the agent of.+ assert detail["saved_by"] == "Switch"+ assert detail["content"].startswith("version: 1")+ assert "Switch expert" in detail["name"]++ with pytest.raises(AgentRefused, match="comes with Switch"):+ await _as(+ tools["agent_id"],+ update_template,+ template_id="official:switch-expert",+ description="mine now",+ )+ with pytest.raises(AgentRefused, match="comes with Switch"):+ await _as(+ tools["agent_id"], delete_template, template_id="official:switch-expert"+ )diff --git a/core/tests/switch_core/bridges/agent/operations/test_template_managed_agents.py b/core/tests/switch_core/bridges/agent/operations/test_template_managed_agents.pynew file mode 100644index 000000000..be12fa0b5--- /dev/null+++ b/core/tests/switch_core/bridges/agent/operations/test_template_managed_agents.py@@ -0,0 +1,776 @@+"""Templates that create managed agents, run by an agent.++Over the same fake protocol as the other template tool tests (real+PostgreSQL, the real template engine and run guards, no Matrix), with a fake+management port standing in for the owner's machines: what it refuses is+what management refuses, and an agent it creates is a real agent row.+"""++from __future__ import annotations++import uuid+from types import SimpleNamespace+from typing import Any++import pytest+import pytest_asyncio+from sqlalchemy import select, update++from switch_core.agent_refusals import AgentRefused+from switch_core.agent_templates import plan_template+from switch_core.bridges.agent.operations import definitions+from switch_core.bridges.agent.operations.agent_management import (+ disable_agent_management,+ enable_agent_management,+)+from switch_core.bridges.agent.operations.callctx import (+ CallContext,+ reset_call_context,+ set_call_context,+)+from switch_core.bridges.agent.operations.definitions import run_template+from switch_core.bridges.agent.protocol.agent_detail import addressing_policy_for+from switch_core.bridges.agent.protocol.agent_management import (+ AgentManagementRefused,+ CheckedPlacement,+ NewManagedAgent,+)+from switch_core.db.models import Agent, Room, Template+from switch_core.template_runs import AgentsNotCreated, RunUndone+from tests.switch_core.bridges.agent.operations.conftest import _make_agent++MACHINES = [+ {+ "id": "m-laptop",+ "name": "laptop",+ "state": "online",+ "providers": [{"provider": "claude", "installed": True, "auth": "ok"}],+ },+ {+ "id": "m-box",+ "name": "box",+ "state": "offline",+ "providers": [{"provider": "codex", "installed": True, "auth": "ok"}],+ },+ {+ "id": "m-server",+ "name": "server",+ "state": "online",+ "providers": [+ {"provider": "claude", "installed": True, "auth": "expired"},+ {"provider": "codex", "installed": True, "auth": "ok"},+ ],+ },+]+++class FakeManagement:+ """The owner's machines as management would answer for them. A machine+ that is offline, or lacks a ready provider, refuses the placement with+ management's reason code."""++ def __init__(self, env: dict[str, Any]) -> None:+ self._env = env+ self.created: list[NewManagedAgent] = []+ self.fail_create: set[str] = set()++ def _machine(self, ref: str) -> dict[str, Any]:+ for machine in MACHINES:+ if ref in (machine["id"], machine["name"]):+ return machine+ raise AgentManagementRefused(+ "not_found",+ f"Nothing was created: your owner has no machine with the id or name '{ref}'.",+ )++ async def list_machines(self, tenant_id: str, owner_id: str) -> list[dict]:+ return MACHINES++ async def check_new_agent(+ self, tenant_id: str, owner_id: str, spec: NewManagedAgent+ ) -> CheckedPlacement:+ machine = self._machine(spec.machine)+ if machine["state"] != "online":+ raise AgentManagementRefused(+ "controller_offline",+ f"Nothing was created: machine '{machine['name']}' is not connected "+ "to Switch (controller_offline).",+ )+ entry = next(+ (p for p in machine["providers"] if p["provider"] == spec.provider), None+ )+ if entry is None:+ raise AgentManagementRefused(+ "provider_not_installed",+ f"Nothing was created: {spec.provider} is not installed on machine "+ f"'{machine['name']}' (provider_not_installed).",+ )+ if entry["auth"] == "expired":+ raise AgentManagementRefused(+ "provider_login_expired",+ f"Nothing was created: the {spec.provider} login on machine "+ f"'{machine['name']}' has expired (provider_login_expired).",+ )+ return CheckedPlacement(+ machine_id=machine["id"],+ machine_name=machine["name"],+ workspaces_dir="/home/me/agents",+ )++ async def create_agent(+ self, tenant_id: str, owner_id: str, spec: NewManagedAgent, protocol: Any+ ) -> dict[str, Any]:+ if spec.name in self.fail_create:+ raise AgentManagementRefused(+ "controller_offline",+ f"Nothing was created: machine '{spec.machine}' went offline.",+ )+ self.created.append(spec)+ async with self._env["session_factory"]() as session:+ agent = await _make_agent(session, spec.name, owner_id, owner_id)+ agent.addressing_policy = addressing_policy_for("owner_only")+ await session.commit()+ agent_id = agent.id+ machine = self._machine(spec.machine)+ return {+ "agent_id": agent_id,+ "name": spec.name,+ "machine": {"id": machine["id"], "name": machine["name"]},+ "desired_state": "running",+ "hint": "",+ }+++class ListeningActor:+ """A new agent's client, taking events once it has started."""++ def __init__(self, order: list[str], name: str) -> None:+ self._order = order+ self._name = name++ async def wait_receiving(self, timeout: float) -> bool:+ self._order.append(f"listening {self._name}")+ return True+++@pytest_asyncio.fixture+async def managed(env, monkeypatch):+ monkeypatch.setattr(definitions, "LISTEN_TIMEOUT_SECONDS", 0.2)+ env["protocol"].config = SimpleNamespace(+ template_max_bytes=64 * 1024, feature_flags={"agent_management": True}+ )+ env["protocol"].telemetry = None+ env["protocol"].service_broker = None+ deleted: list[str] = []++ async def delete_agent(*, agent_id: str) -> None:+ deleted.append(agent_id)+ async with env["session_factory"]() as session:+ agent = await session.get(Agent, agent_id)+ assert agent is not None+ await session.delete(agent)+ await session.commit()++ env["protocol"].delete_agent = delete_agent+ env["deleted"] = deleted+ fake = FakeManagement(env)+ env["management"] = fake+ async with env["session_factory"]() as session:+ await session.execute(+ update(Agent)+ .where(Agent.id == env["agent_id"])+ .values(can_manage_agents=True)+ )+ await session.commit()+ enable_agent_management(fake) # type: ignore[arg-type]+ try:+ yield env+ finally:+ disable_agent_management()+++async def _as(agent_id: str, fn: Any, **kwargs: Any) -> Any:+ token = set_call_context(+ CallContext(agent_id=agent_id, session_key=None, session=None)+ )+ try:+ return await fn(**kwargs)+ finally:+ reset_call_context(token)+++async def _stored(env: dict[str, Any], content: str, kind: str = "group") -> str:+ async with env["session_factory"]() as session:+ template = Template(+ owner_id=env["user_id"],+ name=f"team-{uuid.uuid4().hex[:8]}",+ description="team description",+ kind=kind,+ content=content,+ )+ session.add(template)+ await session.commit()+ return template.id+++async def _agent_names(env: dict[str, Any]) -> set[str]:+ async with env["session_factory"]() as session:+ return {a.name for a in (await session.execute(select(Agent))).scalars()}+++async def _rooms(env: dict[str, Any]) -> list[Room]:+ async with env["session_factory"]() as session:+ return list((await session.execute(select(Room))).scalars())+++TEAM = """\+version: 1+params:+ team: { type: string }+ where: { type: machine, default: [$first] }+agents:+ - name: "{team}-lead"+ description: Leads+ instructions: Lead the team.+ provider: claude+ directory: "{$agents_dir}/{agent}"+ addressing: owner-agents+ - name: "{team}-helper"+ description: Helps+ instructions: Help the lead.+ provider: claude+ model: claude-sonnet+ advanced_config: { effort: high }+ directory: "{$agents_dir}/work/{agent}"+ isolation: isolated+room:+ name: "{team}-room"+ description: Where the team works+ agents: ["{team}-lead", "{team}-helper"]+kickoff: "@{team}-lead start."+"""+++async def test_a_team_template_creates_its_agents_then_the_room(managed):+ template_id = await _stored(managed, TEAM)++ result = await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )++ assert result["room_name"] == "red-room"+ assert [a["name"] for a in result["created_agents"]] == ["red-lead", "red-helper"]+ assert all(a["machine"]["name"] == "laptop" for a in result["created_agents"])+ lead, helper = managed["management"].created+ # `$first` is the first online machine that can run the provider; the+ # agent's own folder there is the machine's workspace for it.+ assert (lead.machine, lead.provider, lead.directory) == ("m-laptop", "claude", None)+ assert (helper.model, helper.advanced_config, helper.isolation) == (+ "claude-sonnet",+ {"effort": "high"},+ "isolated",+ )+ assert helper.directory == "/home/me/agents/work/red-helper"+ async with managed["session_factory"]() as session:+ created = (+ await session.execute(select(Agent).where(Agent.name == "red-lead"))+ ).scalar_one()+ assert created.addressing_policy == addressing_policy_for("owner_and_owner_agents")+ (room,) = await _rooms(managed)+ assert room.name == "red-room"+ assert managed["admin"].sent[-1]["body"].startswith("@red-lead start.")+++async def test_no_machine_that_can_run_every_agent_is_named(managed):+ template = TEAM.replace("provider: claude\n model", "provider: codex\n model")+ template_id = await _stored(managed, template)++ with pytest.raises(AgentsNotCreated) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )+ assert {p.code for p in e.value.problems} == {"machine_unresolved"}+ # Why each machine could not take them, so nobody has to go and look.+ assert "box is offline" in str(e.value)+ assert "claude is not signed in on server" in str(e.value)+++async def test_a_refusal_names_the_agent_and_nothing_is_created(managed):+ template = TEAM.replace("provider: claude\n model", "provider: codex\n model")+ template_id = await _stored(managed, template)++ with pytest.raises(AgentsNotCreated) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red", "where": "laptop"},+ )++ assert {(p.slot, p.code) for p in e.value.problems} == {+ ("red-helper", "provider_not_installed")+ }+ assert "codex is not installed on machine 'laptop'" in str(e.value)+ assert str(e.value).count("Nothing was created") == 1+ assert e.value.reason == "agents_not_created"+ assert managed["management"].created == []+ assert await _rooms(managed) == []+++async def test_each_placement_refusal_carries_managements_reason(managed):+ template_id = await _stored(managed, TEAM)++ for machine, code in (+ ("box", "controller_offline"),+ ("server", "provider_login_expired"),+ ("nowhere", "not_found"),+ ):+ with pytest.raises(AgentsNotCreated) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red", "where": machine},+ )+ assert {p.code for p in e.value.problems} == {code}, machine+ assert managed["management"].created == []+ assert await _rooms(managed) == []+++async def test_a_name_already_taken_refuses_the_run(managed):+ template_id = await _stored(+ managed, TEAM.replace('name: "{team}-lead"', "name: claude-code.bob")+ )++ with pytest.raises(AgentsNotCreated) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )+ assert {(p.slot, p.code) for p in e.value.problems} == {+ ("claude-code.bob", "name_taken")+ }+ assert managed["management"].created == []+++async def test_without_the_capability_nothing_is_created(managed, caplog):+ async with managed["session_factory"]() as session:+ await session.execute(+ update(Agent)+ .where(Agent.id == managed["agent_id"])+ .values(can_manage_agents=False)+ )+ await session.commit()+ template_id = await _stored(managed, TEAM)++ with pytest.raises(AgentsNotCreated) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red", "where": "laptop"},+ )+ assert {p.code for p in e.value.problems} == {"cannot_manage_agents"}+ assert "can manage agents" in str(e.value)+ assert managed["management"].created == []+++async def test_agents_are_deleted_again_when_a_later_one_fails(managed):+ managed["management"].fail_create.add("red-helper")+ template_id = await _stored(managed, TEAM)++ with pytest.raises(RunUndone) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )++ assert e.value.reason == "run_undone"+ assert "red-lead" in str(e.value) and "were deleted" in str(e.value)+ assert "red-lead" not in await _agent_names(managed)+ assert await _rooms(managed) == []+++async def test_agents_are_deleted_again_when_the_room_fails(managed):+ async def broken(config: Any) -> Any:+ raise ValueError("the messaging app is down")++ managed["protocol"].room_service.create_room = broken+ template_id = await _stored(managed, TEAM)++ with pytest.raises(RunUndone, match="the rooms could not be created"):+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )+ assert len(managed["deleted"]) == 2+ assert not {"red-lead", "red-helper"} & await _agent_names(managed)+++async def test_a_kickoff_to_a_new_agent_that_would_ignore_it_is_refused_first(managed):+ template_id = await _stored(+ managed, TEAM.replace(" addressing: owner-agents\n", "")+ )++ with pytest.raises(AgentRefused) as e:+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )+ assert e.value.reason == "kickoff_ignored"+ assert "red-lead" in str(e.value)+ assert "`addressing: owner-agents`" in str(e.value)+ assert managed["management"].created == []+++async def test_an_agent_only_template_creates_the_agent_and_stops(managed):+ template_id = await _stored(+ managed,+ """\+agent:+ name: solo+ instructions: Work alone.+ provider: claude+ machine: laptop+ directory: /srv/solo+""",+ kind="agent",+ )++ result = await _as(managed["agent_id"], run_template, template_id=template_id)++ assert [a["name"] for a in result["created_agents"]] == ["solo"]+ assert managed["management"].created[0].directory == "/srv/solo"+ assert await _rooms(managed) == []+++def _plan(template: str, **kw: Any) -> Any:+ return plan_template(+ template,+ kw.pop("filled", {}),+ kw.pop("inputs", {}),+ builtins={},+ machines=kw.pop("machines", MACHINES),+ )+++def _codes(template: str, **kw: Any) -> set[str]:+ with pytest.raises(AgentsNotCreated) as e:+ _plan(template, **kw)+ return {p.code for p in e.value.problems}+++def test_an_agent_must_say_how_it_runs():+ bare = "agent:\n name: a\n instructions: Hi.\n"+ assert _codes(bare) == {"machine_unsaid", "provider_unsaid", "directory_unsaid"}+++def test_a_location_names_a_machine_only_when_it_is_one():+ def placed(location: str, provider: str = "claude") -> str:+ template = (+ f"agent:\n name: a\n instructions: Hi.\n provider: {provider}\n"+ f" location: {location}\n directory: /x\n"+ )+ (agent,) = _plan(template).new_agents+ return agent.machine++ # A Console's "this computer" or SSH host means nothing to the server:+ # the first online machine that can run the agent stands in.+ assert placed("local") == "m-laptop"+ assert placed("dev-vm", provider="codex") == "m-server"+ assert placed("box", provider="codex") == "m-box"+++def test_join_names_the_existing_rooms_to_add_the_agent_to():+ template = (+ "agent:\n name: a\n instructions: Hi.\n provider: claude\n"+ " machine: laptop\n directory: /x\n join: [lobby]\n"+ )+ (agent,) = _plan(template).new_agents+ assert agent.joins == ["lobby"]+++async def test_a_new_agent_joins_an_existing_room_or_the_run_is_refused(managed):+ added: list[tuple[str, list[str]]] = []++ async def add_agents_to_room(room_id: str, agent_ids: list[str]) -> None:+ added.append((room_id, agent_ids))++ managed["protocol"].room_service.add_agents_to_room = add_agents_to_room+ async with managed["session_factory"]() as session:+ lobby = Room(+ transport_room_id="!lobby:test.local",+ name="lobby",+ description="d",+ channel_type="channel_public",+ owner_id=managed["user_id"],+ )+ session.add(lobby)+ await session.commit()+ lobby_id = lobby.id+ template = """\+agent:+ name: joiner+ instructions: Join.+ provider: claude+ machine: laptop+ directory: /srv/joiner+ join: [JOIN]+"""+ unknown = await _stored(managed, template.replace("JOIN", "nowhere"), kind="agent")+ with pytest.raises(AgentsNotCreated) as e:+ await _as(managed["agent_id"], run_template, template_id=unknown)+ assert {p.code for p in e.value.problems} == {"join_unknown_room"}+ assert managed["management"].created == []++ known = await _stored(managed, template.replace("JOIN", "lobby"), kind="agent")+ result = await _as(managed["agent_id"], run_template, template_id=known)+ (created,) = result["created_agents"]+ assert added == [(lobby_id, [created["agent_id"]])]+++def test_a_provider_chain_takes_the_first_ready_on_the_machine():+ template = """\+params:+ coder: { type: provider, default: [claude, codex] }+agent:+ name: a+ instructions: Hi.+ provider: "{coder}"+ machine: server+ directory: /x+"""+ (agent,) = _plan(template).new_agents+ # server's claude login has expired, so codex.+ assert agent.provider == "codex"+++def test_a_repo_is_cloned_by_the_agent_and_grants_nothing():+ template = """\+agent:+ name: a+ instructions: Hi.+ provider: claude+ machine: laptop+ directory: /x+ repo: https://gitlab.com/acme/widgets.git+ connections:+ - { service: github, access: write, repos: [acme/tools] }+ - atlassian+"""+ (agent,) = _plan(template).new_agents+ github, atlassian = agent.connections+ assert (github.service, github.access, github.repositories) == (+ "github",+ "write",+ ["acme/tools"],+ )+ assert (atlassian.service, atlassian.repositories) == ("atlassian", [])+ assert "clone https://gitlab.com/acme/widgets.git" in agent.instructions+++async def test_connections_need_connections_on(managed):+ template_id = await _stored(+ managed,+ """\+agent:+ name: solo+ instructions: Work alone.+ provider: claude+ machine: laptop+ directory: /srv/solo+ connections: [github]+""",+ kind="agent",+ )++ with pytest.raises(AgentsNotCreated) as e:+ await _as(managed["agent_id"], run_template, template_id=template_id)+ assert {p.code for p in e.value.problems} == {"connections_off"}+ assert managed["management"].created == []+++async def test_an_unknown_messaging_app_is_refused_before_any_agent(managed):+ template_id = await _stored(+ managed,+ TEAM.replace(+ ' name: "{team}-room"\n', ' name: "{team}-room"\n bridge: Nowhere\n'+ ),+ )++ with pytest.raises(ValueError, match="Unknown bridge"):+ await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )+ assert managed["management"].created == []+++async def test_the_rooms_wait_until_the_new_agents_are_listening(managed):+ order: list[str] = []+ names: dict[str, str] = {}++ async def create_room(config: Any) -> Any:+ order.append(f"room {config.name}")+ return await original(config)++ original = managed["protocol"].room_service.create_room+ managed["protocol"].room_service.create_room = create_room+ lifecycle = managed["protocol"].client_lifecycle++ def get_by_agent_id(agent_id: str) -> Any:+ return ListeningActor(order, names.setdefault(agent_id, agent_id))++ lifecycle.get_by_agent_id = get_by_agent_id+ template_id = await _stored(managed, TEAM)++ result = await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )++ assert all(a["listening"] for a in result["created_agents"])+ assert order[-1] == "room red-room"+ assert len([o for o in order if o.startswith("listening")]) == 2+++async def test_an_agent_whose_client_never_starts_is_reported(managed):+ template_id = await _stored(managed, TEAM)++ result = await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"team": "red"},+ )++ assert [a["listening"] for a in result["created_agents"]] == [False, False]+++def test_slots_show_what_a_shared_param_says_and_each_connection():+ from switch_core.agent_templates import agent_slots++ (lead, helper) = agent_slots(+ TEAM.replace(+ " addressing: owner-agents\n",+ " addressing: owner-agents\n connections:\n"+ " - { service: github, access: write, repos: [acme/a] }\n"+ " repo: https://github.com/acme/b\n",+ )+ )+ assert (lead.machine, helper.machine) == ("{where}", "{where}")+ assert lead.connections == [+ {"service": "github", "access": "write", "repos": ["acme/a"]}+ ]+++V2_EXPERT = """\+version: 2+params:+ start_in: { type: enum, enum: [nowhere, new_room], default: new_room }+ machine: { type: machine, default: [$first] }+resources:+ expert:+ type: agent+ display_name: Switch expert+ instructions: Answer questions about Switch.+ provider: claude+ machine: "{machine}"+ directory: "{$agents_dir}/{expert.name}"+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ description: Where you ask about Switch.+ agents: [expert]+ kickoff: "@{expert.name} hi."+"""+++async def test_a_v2_template_runs_and_opens_its_agent_to_its_room(managed):+ template_id = await _stored(managed, V2_EXPERT, kind="agent")++ result = await _as(managed["agent_id"], run_template, template_id=template_id)++ assert result["room_name"] == "Ask switch-expert"+ assert [a["name"] for a in result["created_agents"]] == ["switch-expert"]+ async with managed["session_factory"]() as session:+ agent = (+ await session.execute(select(Agent).where(Agent.name == "switch-expert"))+ ).scalar_one()+ rules = agent.addressing_policy["rules"]+ assert any(rule.get("rooms") == [result["room_id"]] for rule in rules)+ assert managed["admin"].sent[-1]["body"].startswith("@switch-expert hi.")+++async def test_a_v2_template_with_its_room_off_creates_the_agent_alone(managed):+ template_id = await _stored(managed, V2_EXPERT, kind="agent")++ result = await _as(+ managed["agent_id"],+ run_template,+ template_id=template_id,+ inputs={"start_in": "nowhere"},+ )++ assert "room_id" not in result+ async with managed["session_factory"]() as session:+ agent = (+ await session.execute(select(Agent).where(Agent.name == "switch-expert"))+ ).scalar_one()+ assert agent.addressing_policy is None+ assert await _rooms(managed) == []+++async def test_users_with_no_messaging_app_are_refused_before_any_agent(managed):+ template_id = await _stored(+ managed,+ V2_EXPERT.replace(+ " agents: [expert]\n", ' agents: [expert]\n users: ["ada"]\n'+ ),+ kind="agent",+ )++ with pytest.raises(ValueError, match="on no messaging app"):+ await _as(managed["agent_id"], run_template, template_id=template_id)+ assert managed["management"].created == []diff --git a/core/tests/switch_core/connections/fake_vendor.py b/core/tests/switch_core/connections/fake_vendor.pyindex 1fb2f52a1..9d33c5053 100644--- a/core/tests/switch_core/connections/fake_vendor.py+++ b/core/tests/switch_core/connections/fake_vendor.py@@ -53,6 +53,7 @@ class FakeVendor:self.connections_revoked: list[ConnectionSecret] = []self.grant_error: Exception | None = Noneself.checked: list[tuple[str, dict[str, Any]]] = []+ self.resolved: list[list[str]] = []async def refresh(self, secret: ConnectionSecret) -> ConnectionSecret:self.refreshes += 1@@ -97,6 +98,17 @@ class FakeVendor:async def revoke_connection(self, secret: ConnectionSecret) -> None:self.connections_revoked.append(secret)+ async def resolve_repositories(+ self, access_token: str, names: list[str]+ ) -> dict[str, Any]:+ """Every repository is reachable, in installation 123, numbered from+ 456 in the order named."""+ self.resolved.append(list(names))+ return {+ "installation_id": 123,+ "repository_ids": [456 + i for i in range(len(names))],+ }+async def check_grant(self, access_token: str, request: IssueRequest) -> dict[str, Any]:diff --git a/core/tests/switch_core/gateway/test_template_http.py b/core/tests/switch_core/gateway/test_template_http.pyindex 415ce0858..dca9f1d8a 100644--- a/core/tests/switch_core/gateway/test_template_http.py+++ b/core/tests/switch_core/gateway/test_template_http.py@@ -45,6 +45,11 @@ _AWKWARD_DOCUMENT = ()+def _stored(listing: list[dict]) -> list[dict]:+ """A listing without the templates that come with Switch."""+ return [t for t in listing if not t["official"]]++def _config() -> SwitchConfig:return SwitchConfig( # type: ignore[call-arg]db_host="localhost",@@ -225,7 +230,7 @@ class TestOverTheWire:# The point of it: nothing was created by asking.listing = await client.get("/templates")- assert listing.json() == []+ assert _stored(listing.json()) == []async def test_a_document_that_is_not_yaml_is_refused(self, session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]@@ -252,7 +257,7 @@ class TestOverTheWire:)assert refused.status_code == 422assert "Not valid YAML" in refused.json()["detail"]- assert (await client.get("/templates")).json() == []+ assert _stored((await client.get("/templates")).json()) == []async def test_everything_else_it_says_is_advice(self, session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]@@ -371,7 +376,10 @@ class TestOverTheWire:for who in ("alice", "bob"):listing = await _client(session_factory, users[who]).get("/templates")assert listing.status_code == 200- assert {t["name"] for t in listing.json()} == {"alice-room", "bob-room"}+ assert {t["name"] for t in _stored(listing.json())} == {+ "alice-room",+ "bob-room",+ }async def test_search_narrows_the_catalogue(self, session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]@@ -436,7 +444,7 @@ class TestOverTheWire:await _upload(_client(session_factory, users["bob"]), name="deploy-room")listing = await _client(session_factory, users["alice"]).get("/templates")- assert len(listing.json()) == 2+ assert len(_stored(listing.json())) == 2async def test_replacing_the_document_bumps_the_revision(self, session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]@@ -548,7 +556,7 @@ class TestOverTheWire:assert response.status_code == 422listing = await client.get("/templates", params={"q": "smuggled"})- assert listing.json() == []+ assert _stored(listing.json()) == []async def test_a_body_naming_the_owner_is_refused_outright(self, session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]@@ -565,3 +573,29 @@ class TestOverTheWire:unchanged = await client.get(f"/templates/{created['id']}")assert unchanged.json()["owner_id"] == users["alice"].id+++async def test_an_official_template_is_listed_served_and_never_changed(+ session_factory: async_sessionmaker[AsyncSession], users: dict[str, User]+) -> None:+ client = _client(session_factory, users["alice"])+ listing = (await client.get("/templates")).json()+ (official,) = [t for t in listing if t["official"]]+ assert (official["id"], official["owner_name"], official["can_edit"]) == (+ "official:switch-expert",+ "Switch",+ False,+ )+ detail = (await client.get("/templates/official:switch-expert")).json()+ # The test config leaves agent management off: the Console-run document.+ assert detail["content"].startswith("version: 1")+ content = await client.get("/templates/official:switch-expert/content")+ assert content.status_code == 200+ patched = await client.patch(+ "/templates/official:switch-expert", json={"description": "mine"}+ )+ assert patched.status_code == 403+ deleted = await client.delete("/templates/official:switch-expert")+ assert deleted.status_code == 403+ assert (await client.get("/templates/official:nope")).status_code == 404diff --git a/core/tests/switch_core/gateway/test_template_routes.py b/core/tests/switch_core/gateway/test_template_routes.pyindex 9108d1b3a..3b5cca784 100644--- a/core/tests/switch_core/gateway/test_template_routes.py+++ b/core/tests/switch_core/gateway/test_template_routes.py@@ -7,6 +7,8 @@ someone else's is refused.from __future__ import annotations+from typing import Any+import pytestfrom fastapi import HTTPExceptionfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -29,6 +31,14 @@ from switch_core.gateway.templates import (from tests.switch_core.gateway.agent_route_harness import add_user_TEMPLATE_STORE = TemplateStore()+++async def _listed(*args: Any, **kwargs: Any) -> list[Any]:+ """The catalogue without the templates that come with Switch, which every+ listing carries (see test_official_templates)."""+ return [t for t in await list_templates(*args, **kwargs) if not t.official]++_USER_STORE = UserStore()@@ -109,6 +119,7 @@ class TestUploadAndFetch:_USER_STORE,owner,await _is_admin(session, owner),+ config=_config(),)assert fetched.content == _AWKWARD_DOCUMENT@@ -118,6 +129,7 @@ class TestUploadAndFetch:_TEMPLATE_STORE,owner,await _is_admin(session, owner),+ config=_config(),)assert raw.body.decode("utf-8") == _AWKWARD_DOCUMENTassert raw.media_type == "application/x-yaml"@@ -170,6 +182,7 @@ class TestUploadAndFetch:_USER_STORE,owner,await _is_admin(session, owner),+ config=_config(),)assert exc.value.status_code == 404@@ -247,12 +260,13 @@ class TestCatalogue:# Listed identically whoever is asking.for caller in (alice, bob):- listed = await list_templates(+ listed = await _listed(session,_TEMPLATE_STORE,_USER_STORE,caller,await _is_admin(session, caller),+ config=_config(),)assert {t.name for t in listed} == {"alice-room", "bob-room"}assert {t.owner_name for t in listed} == {"alice", "bob"}@@ -265,12 +279,13 @@ class TestCatalogue:await session.commit()await _create(session, owner, name="t", content=_AWKWARD_DOCUMENT)- listed = await list_templates(+ listed = await _listed(session,_TEMPLATE_STORE,_USER_STORE,owner,await _is_admin(session, owner),+ config=_config(),)assert not hasattr(listed[0], "content")assert listed[0].size_bytes == len(_AWKWARD_DOCUMENT.encode("utf-8"))@@ -285,13 +300,14 @@ class TestCatalogue:await _create(session, owner, name="other", description="for DEPLOYing")await _create(session, owner, name="unrelated", description="x")- hits = await list_templates(+ hits = await _listed(session,_TEMPLATE_STORE,_USER_STORE,owner,await _is_admin(session, owner),q="deploy",+ config=_config(),)assert {t.name for t in hits} == {"deploy-room", "other"}@@ -304,13 +320,14 @@ class TestCatalogue:await _create(session, owner, name="a", kind="room")await _create(session, owner, name="b", kind="group")- hits = await list_templates(+ hits = await _listed(session,_TEMPLATE_STORE,_USER_STORE,owner,await _is_admin(session, owner),kind="group",+ config=_config(),)assert {t.name for t in hits} == {"b"}@@ -377,6 +394,7 @@ class TestOwnership:_USER_STORE,bob,await _is_admin(session, bob),+ config=_config(),)assert fetched.content == _AWKWARD_DOCUMENT@@ -566,12 +584,13 @@ class TestVisibility:await _is_admin(session, alice),)for who, expected in ((alice, {"mine"}), (bob, set())):- listed = await list_templates(+ listed = await _listed(session,_TEMPLATE_STORE,_USER_STORE,who,await _is_admin(session, who),+ config=_config(),)assert {t.name for t in listed} == expectedwith pytest.raises(HTTPException) as exc:@@ -582,6 +601,7 @@ class TestVisibility:_USER_STORE,bob,await _is_admin(session, bob),+ config=_config(),)assert exc.value.status_code == 404@@ -688,19 +708,21 @@ class TestVisibility:alice,await _is_admin(session, alice),)- (row,) = await list_templates(+ (row,) = await _listed(session,_TEMPLATE_STORE,_USER_STORE,bob,await _is_admin(session, bob),+ config=_config(),)assert (row.can_edit, row.can_manage) == (True, False)- (own,) = await list_templates(+ (own,) = await _listed(session,_TEMPLATE_STORE,_USER_STORE,alice,await _is_admin(session, alice),+ config=_config(),)assert (own.can_edit, own.can_manage) == (True, True)diff --git a/core/tests/switch_core/management/harness.py b/core/tests/switch_core/management/harness.pyindex a97c06df0..2ac50fa07 100644--- a/core/tests/switch_core/management/harness.py+++ b/core/tests/switch_core/management/harness.py@@ -124,6 +124,10 @@ class _FakeClientLifecycle:def start_client(self, client: Client) -> None:return None+ def get_by_agent_id(self, agent_id: str) -> None:+ """No client is ever started here."""+ return None+class _NoBridges:def bridges_for_tenant(self, tenant_id: str) -> list[object]:diff --git a/core/tests/switch_core/management/test_agent_operations.py b/core/tests/switch_core/management/test_agent_operations.pyindex 7ff0c44d1..873f20794 100644--- a/core/tests/switch_core/management/test_agent_operations.py+++ b/core/tests/switch_core/management/test_agent_operations.py@@ -22,19 +22,27 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.addressing import owner_only_policyfrom switch_core.bridges.agent.mcp.server import mcp-from switch_core.bridges.agent.operations import all_operations+from switch_core.bridges.agent.operations import all_operations, definitionsfrom switch_core.bridges.agent.operations import context as op_contextfrom switch_core.bridges.agent.operations.agent_management import (disable_agent_management,)+from switch_core.bridges.agent.protocol.agent_detail import addressing_policy_forfrom switch_core.db.models import (Agent,AgentDefinition,ApiKey,Client,+ ServiceGrant,+ Template,User,)+from switch_core.gateway import dependencies as gw_deps+from switch_core.gateway import rooms as gateway_rooms+from switch_core.gateway.rooms import router as rooms_router+from tests.switch_core.connections.github_seed import connect_githubfrom tests.switch_core.management.harness import (+ TEST_KEYRING,WORKSPACES_DIR,EnrolledController,Harness,@@ -1024,3 +1032,345 @@ class TestGetAdvancedConfig:assert cursor.json()["result"] == []assert unknown.status_code == 400, unknown.textassert "unknown provider 'vim'" in unknown.json()["detail"]+++SOLO_TEMPLATE = """\+params:+ where: { type: machine, default: [$first] }+agent:+ name: solo+ description: Works alone+ instructions: Work alone.+ provider: claude+ directory: "{$agents_dir}/{agent}"+ isolation: isolated+ addressing: owner-agents+ repo: https://github.com/acme/widgets+ connections:+ - { service: github, repos: [acme/widgets] }+"""+++class _NoRooms:+ """The room half of the template engine, for templates with no room:+ only the builtins an agent's fields may read."""++ async def builtins_for(self, **kwargs: Any) -> dict[str, str]:+ return {"$creator": kwargs["name"], "$creator_email": kwargs["email"]}++ async def resolve_defaults(+ self, text: str, inputs: dict[str, Any] | None+ ) -> dict[str, Any] | None:+ return inputs+++async def _template(harness: Harness, owner: User, content: str) -> str:+ harness.protocol.config.template_max_bytes = 64 * 1024 # type: ignore[attr-defined]+ harness.protocol.config.feature_flags = {"agent_management": True} # type: ignore[attr-defined]+ harness.protocol.room_yaml_service = _NoRooms # type: ignore[assignment,method-assign]+ async with harness.session_factory() as session:+ template = Template(+ owner_id=owner.id,+ name="solo",+ description="One agent",+ kind="agent",+ content=content,+ )+ session.add(template)+ await session.commit()+ return template.id+++def _short_listen(monkeypatch: pytest.MonkeyPatch) -> None:+ """No agent client starts in these tests; do not wait long for one."""+ monkeypatch.setattr(definitions, "LISTEN_TIMEOUT_SECONDS", 0.1)+ monkeypatch.setattr(gateway_rooms, "LISTEN_TIMEOUT_SECONDS", 0.1)++[email protected]("_short_listen")+class TestRunTemplateCreatesManagedAgents:+ """A template run through the real management service and broker: the+ agent is created on the owner's machine with its definition, addressing+ and GitHub grant, or refused with management's reason and nothing made."""++ async def test_creates_the_agent_with_its_definition_and_grant(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ harness.protocol.service_broker = harness.broker+ owner = await add_member(harness.session_factory, "ada")+ async with harness.session_factory() as session:+ await connect_github(session, owner.id, TEST_KEYRING)+ await session.commit()+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(client, controller)+ agent_id, key = await _agent_with_key(+ harness, owner, "helper", can_manage_agents=True+ )+ template_id = await _template(harness, owner, SOLO_TEMPLATE)++ response = await _call(+ client,+ agent_id,+ "run_template",+ bearer(key),+ {"template_id": template_id},+ )++ assert response.status_code == 200, response.text+ (created,) = response.json()["result"]["created_agents"]+ assert created["name"] == "solo"+ assert created["machine"] == {"id": controller.controller_id, "name": "laptop"}+ agent = await _agent_row(harness, "solo")+ assert agent is not None and agent.owner_id == owner.id+ assert agent.addressing_policy == addressing_policy_for(+ "owner_and_owner_agents"+ )+ async with harness.session_factory() as session:+ row = (+ await session.execute(+ select(AgentDefinition).where(AgentDefinition.agent_id == agent.id)+ )+ ).scalar_one()+ grant = (+ await session.execute(+ select(ServiceGrant).where(ServiceGrant.agent_id == agent.id)+ )+ ).scalar_one()+ assert row.controller_id == controller.controller_id+ assert row.definition["isolation"] == "isolated"+ assert row.definition["directory"] == f"{WORKSPACES_DIR}/solo"+ assert (+ "clone https://github.com/acme/widgets into it"+ in row.definition["instructions"]+ )+ assert (grant.service, grant.resources) == (+ "github",+ {"installation_id": 123, "repository_ids": [456]},+ )+ assert harness.vendor.resolved == [["acme/widgets"]]++ async def test_an_offline_machine_refuses_with_managements_reason(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ agent_id, key = await _agent_with_key(+ harness, owner, "helper", can_manage_agents=True+ )+ template_id = await _template(+ harness,+ owner,+ SOLO_TEMPLATE.replace(+ " connections:\n - { service: github, repos: [acme/widgets] }\n", ""+ ),+ )++ response = await _call(+ client,+ agent_id,+ "run_template",+ bearer(key),+ {"template_id": template_id, "inputs": {"where": controller.controller_id}},+ )++ assert response.status_code == 400, response.text+ detail = response.json()["detail"]+ assert detail.startswith("Nothing was created.")+ assert "(controller_offline)" in detail+ assert await _agent_row(harness, "solo") is None++ async def test_a_grant_the_owner_cannot_make_refuses_before_creating(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ harness.protocol.service_broker = harness.broker+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(client, controller)+ agent_id, key = await _agent_with_key(+ harness, owner, "helper", can_manage_agents=True+ )+ template_id = await _template(harness, owner, SOLO_TEMPLATE)++ response = await _call(+ client, agent_id, "run_template", bearer(key), {"template_id": template_id}+ )++ assert response.status_code == 400, response.text+ detail = response.json()["detail"]+ # Never connected GitHub: the broker's reason, and no agent.+ assert "solo: github: Connect GitHub" in detail+ assert await _agent_row(harness, "solo") is None+++def _gateway_agent(machine: str, name: str = "solo", **overrides: Any) -> dict:+ return {+ "slot": name,+ "name": name,+ "description": "Works alone",+ "display_name": None,+ "instructions": "Work alone.",+ "provider": "claude",+ "machine": machine,+ "model": None,+ "advanced_config": {},+ "isolation": "shared",+ "auto_approve": False,+ "directory": None,+ "addressing": "owner",+ "connections": [],+ **overrides,+ }++[email protected]("_short_listen")+class TestTheConsoleRunsATemplateWithAgents:+ """`POST /gateway/rooms/from-template`, the Use page's one request: the+ person's own machines, checked whole, refused with every problem."""++ @pytest.fixture(autouse=True)+ def _rooms(self, harness: Harness) -> None:+ harness.gateway_app.include_router(rooms_router, prefix="/rooms")+ harness.gateway_app.dependency_overrides[gw_deps.get_room_yaml_service] = (+ lambda: _NoRooms()+ )++ async def test_creates_the_agents_on_the_persons_machine(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(client, controller)++ response = await client.post(+ "/gateway/rooms/from-template",+ json={+ "agents": [+ _gateway_agent("laptop"),+ _gateway_agent(+ controller.controller_id,+ name="pair",+ isolation="isolated",+ addressing="anyone",+ ),+ ],+ "yaml": None,+ "template_name": "duo",+ },+ cookies=cookies_for(owner),+ )++ assert response.status_code == 201, response.text+ body = response.json()+ assert [a["name"] for a in body["created_agents"]] == ["solo", "pair"]+ assert body["room"] is None+ pair = await _agent_row(harness, "pair")+ assert pair is not None and pair.owner_id == owner.id+ assert pair.addressing_policy is None++ async def test_refuses_with_every_problem_and_creates_nothing(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(+ client, controller, providers=[provider("claude", auth="missing")]+ )++ response = await client.post(+ "/gateway/rooms/from-template",+ json={+ "agents": [+ _gateway_agent("laptop"),+ _gateway_agent("nowhere", name="pair"),+ _gateway_agent("laptop", name="Bad Name"),+ ],+ "yaml": None,+ "template_name": "trio",+ },+ cookies=cookies_for(owner),+ )++ assert response.status_code == 409, response.text+ body = response.json()+ assert body["code"] == "agents_not_created"+ assert {(p["slot"], p["code"]) for p in body["problems"]} == {+ ("solo", "provider_login_missing"),+ ("pair", "not_found"),+ ("Bad Name", "invalid_name"),+ }+ assert await _agent_row(harness, "solo") is None+++DOCUMENT_TEMPLATE = """\+version: 2+params:+ name: { type: string, default: Helper }+ machine: { type: machine, default: [$first] }+resources:+ helper:+ type: agent+ display_name: "{name}"+ instructions: Help.+ provider: claude+ machine: "{machine}"+ directory: "{$agents_dir}/{helper.name}"+ addressing: anyone+"""++[email protected]("_short_listen")+class TestTheConsoleRunsAVersion2Template:+ """`POST /gateway/rooms/from-template-document`: the server works the+ agents out of the document and the inputs, on the person's machines."""++ @pytest.fixture(autouse=True)+ def _rooms(self, harness: Harness) -> None:+ harness.gateway_app.include_router(rooms_router, prefix="/rooms")+ harness.gateway_app.dependency_overrides[gw_deps.get_room_yaml_service] = (+ lambda: _NoRooms()+ )++ async def test_creates_the_agent_on_the_first_machine_that_can_run_it(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(client, controller)++ response = await client.post(+ "/gateway/rooms/from-template-document",+ json={+ "template": DOCUMENT_TEMPLATE,+ "inputs": {"name": "Ada helper"},+ "template_name": "helper",+ },+ cookies=cookies_for(owner),+ )++ assert response.status_code == 201, response.text+ (created,) = response.json()["created_agents"]+ assert created["name"] == "ada-helper"+ assert created["machine"]["name"] == "laptop"+ agent = await _agent_row(harness, "ada-helper")+ assert agent is not None and agent.addressing_policy is None++ async def test_no_machine_that_can_run_it_is_refused_with_the_reason(+ self, harness: Harness, client: httpx.AsyncClient+ ) -> None:+ owner = await add_member(harness.session_factory, "ada")+ controller = await enroll_console(harness, client, owner, name="laptop")+ await _online(+ client, controller, providers=[provider("claude", auth="expired")]+ )++ response = await client.post(+ "/gateway/rooms/from-template-document",+ json={"template": DOCUMENT_TEMPLATE, "template_name": "helper"},+ cookies=cookies_for(owner),+ )++ assert response.status_code == 409, response.text+ body = response.json()+ assert {p["code"] for p in body["problems"]} == {"machine_unresolved"}+ assert "claude is not signed in on laptop" in body["detail"]diff --git a/core/tests/switch_core/test_official_templates.py b/core/tests/switch_core/test_official_templates.pynew file mode 100644index 000000000..a8466c823--- /dev/null+++ b/core/tests/switch_core/test_official_templates.py@@ -0,0 +1,50 @@+"""Templates that come with Switch: served on every workspace from the+package, the document chosen by the agent_management flag, never changed."""++from __future__ import annotations++from pathlib import Path++import yaml++from switch_core.official_templates import (+ official_template,+ official_templates,+)+from switch_core.template_lint import lint_template++_REPO = Path(__file__).resolve().parents[3]+_PACKAGED = _REPO / "core" / "switch_core" / "official_templates"+++def test_the_switch_expert_copies_match_the_repository():+ """The package carries copies of switch-expert/ at the repository root;+ an edit to one side must reach the other."""+ for name in ("template.yaml", "template.console.yaml", "AGENT.md"):+ assert (_PACKAGED / "switch-expert" / name).read_text() == (+ _REPO / "switch-expert" / name+ ).read_text(), (+ f"core/switch_core/official_templates/switch-expert/{name} is stale"+ )+++def test_the_flag_picks_the_document():+ managed = official_template("official:switch-expert", agent_management=True)+ console = official_template("official:switch-expert", agent_management=False)+ assert managed is not None and console is not None+ assert yaml.safe_load(managed.content)["version"] == 2+ assert yaml.safe_load(console.content)["version"] == 1+++def test_the_instructions_are_written_in_and_the_documents_are_clean():+ for flag in (True, False):+ (template,) = official_templates(flag)+ data = yaml.safe_load(template.content)+ agent = data["resources"]["expert"] if "resources" in data else data["agent"]+ assert len(agent["instructions"]) > 1000+ result = lint_template(template.content)+ assert result.errors == [] and result.warnings == []+++def test_an_unknown_official_id_is_none():+ assert official_template("official:nope", agent_management=True) is Nonediff --git a/core/tests/switch_core/test_template_lint.py b/core/tests/switch_core/test_template_lint.pyindex 757dfd249..7b4506ae2 100644--- a/core/tests/switch_core/test_template_lint.py+++ b/core/tests/switch_core/test_template_lint.py@@ -456,6 +456,7 @@ def test_group_and_agents_keys_are_known():result = lint_template("params:\n team:\n type: string\n""agents:\n - name: '{team}-triager'\n"+ " provider: claude\n location: local\n directory: /tmp/t\n""group:\n name: '{team}'\nrooms:\n - name: '{team} lobby'\n"" description: d\nlinks: []\n")@@ -508,3 +509,86 @@ def test_the_policy_fields_are_known_param_fields():def test_an_agent_template_without_a_room_is_not_told_agent_is_unused():result = lint_template("agent:\n name: a\n instructions: x\n")assert "unused_param" not in {w.code for w in result.warnings}+++class TestAgentRuntime:+ """A template that creates an agent must say what runs it, where, and in+ which folder: Switch Console supplies none of the three. Said at save as a+ warning, never an error, so a document is always storable."""++ def test_an_agent_with_nothing_said_is_warned_about_each_setting(self) -> None:+ result = lint_template("agent:\n name: helper\n instructions: Help.\n")+ assert result.ok, "an incomplete agent template must still be storable"+ unsaid = [f for f in result.warnings if f.code == "agent_runtime_unsaid"]+ assert [f.subject for f in unsaid] == ["provider", "location", "directory"]+ assert "which coding agent runs helper" in unsaid[0].message++ def test_fields_on_the_entry_say_it(self) -> None:+ result = lint_template(+ "agent:\n name: helper\n provider: claude\n location: local\n"+ " directory: /tmp/helper\n instructions: Help.\n"+ )+ assert "agent_runtime_unsaid" not in _codes(result.warnings)++ def test_a_param_no_field_reads_says_it_for_every_agent(self) -> None:+ result = lint_template(+ "params:\n"+ " provider: {type: provider, default: [claude]}\n"+ " where: {type: location, default: local}\n"+ " dir: {type: directory, default: '{$agents_dir}/{agent}'}\n"+ "agents:\n - name: a\n instructions: A.\n"+ " - name: b\n instructions: B.\n"+ )+ assert "agent_runtime_unsaid" not in _codes(result.warnings)++ def test_a_param_one_agent_reads_does_not_cover_another(self) -> None:+ result = lint_template(+ "params:\n where: {type: location, default: local}\n"+ "agents:\n"+ " - {name: a, provider: claude, location: '{where}', directory: /a, instructions: A.}\n"+ " - {name: b, provider: claude, directory: /b, instructions: B.}\n"+ )+ unsaid = [f for f in result.warnings if f.code == "agent_runtime_unsaid"]+ assert [(f.subject, "b" in f.message) for f in unsaid] == [("location", True)]++ def test_a_room_template_is_not_asked_about_agents(self) -> None:+ result = lint_template("room:\n name: r\n")+ assert "agent_runtime_unsaid" not in _codes(result.warnings)++ def test_a_runtime_param_for_every_agent_is_not_unused(self) -> None:+ result = lint_template(+ "params:\n where: {type: location, default: local}\n"+ "agent:\n name: a\n provider: claude\n directory: /a\n instructions: A.\n"+ )+ assert "unused_param" not in _codes(result.warnings)+ assert "agent_runtime_unsaid" not in _codes(result.warnings)+++def test_agent_inside_an_agents_entry_is_that_entrys_name():+ text = """\+agents:+ - name: lead+ instructions: Lead.+ provider: claude+ machine: laptop+ directory: "{$agents_dir}/{agent}"+room:+ name: team+ agents: [lead]+"""+ result = lint_template(text)+ assert not [w for w in result.warnings if "'{agent}'" in w.message]+++def test_agent_in_a_team_room_is_still_undeclared():+ text = """\+agents:+ - name: lead+ instructions: Lead.+room:+ name: "{agent} room"+ agents: [lead]+"""+ result = lint_template(text)+ (warning,) = [w for w in result.warnings if "'{agent}'" in w.message]+ assert "ambiguous" in warning.messagediff --git a/core/tests/switch_core/test_template_v2.py b/core/tests/switch_core/test_template_v2.pynew file mode 100644index 000000000..417f2b8d5--- /dev/null+++ b/core/tests/switch_core/test_template_v2.py@@ -0,0 +1,208 @@+"""Version 2 templates: resources with a key and a type, references by key,+and `if:` on resources, params and field values, compiled into the version 1+document the rest of the engine runs."""++from __future__ import annotations++import pytest+import yaml++from switch_core.agent_templates import agent_slots, plan_template, template_kind+from switch_core.template_lint import lint_template+from switch_core.template_v2 import TemplateError, compile_v2, holds++EXPERT = """\+version: 2+params:+ name: { type: string, default: Switch expert }+ start_in:+ type: enum+ enum: [nowhere, new_room, existing_room]+ default: nowhere+ existing_room:+ type: room+ if: "{start_in} == existing_room"+ bridge: { type: bridge, default: [Slack, $first], required: false }+ provider: { type: provider, default: [claude, codex], input: advanced }+ machine: { type: machine, default: [$first], input: advanced }+ directory:+ type: directory+ default: "{$agents_dir}/{expert.name}"+ input: advanced+resources:+ expert:+ type: agent+ display_name: "{name}"+ instructions: Answer questions about Switch.+ provider: "{provider}"+ machine: "{machine}"+ directory: "{directory}"+ repo: https://github.com/sandbox-quantum/switch+ join: ["{existing_room}"]+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ description: Where you ask {expert.name} about Switch.+ bridge: "{bridge}"+ agents: [expert]+ users: ["{$creator}"]+ kickoff: "@{expert.name} hi."+"""++MACHINES = [+ {+ "id": "m-laptop",+ "name": "laptop",+ "state": "online",+ "providers": [{"provider": "claude", "installed": True, "auth": "ok"}],+ }+]+++def _compiled(inputs: dict, text: str = EXPERT) -> dict:+ compiled = compile_v2(text, inputs, {"$creator": "ada"})+ return yaml.safe_load(compiled.document)+++def test_conditions():+ assert holds("{a}", {"a": True}) and not holds("{a}", {"a": ""})+ assert holds("{a} == x", {"a": "x"}) and holds("{a} != x", {"a": "y"})+ assert not holds("{a} == x", {})+ with pytest.raises(TemplateError):+ holds("a == x", {"a": "x"})+++def test_nowhere_creates_the_agent_alone_and_open_to_anyone():+ doc = _compiled({})+ (agent,) = doc["agents"]+ assert agent["name"] == "switch-expert"+ assert agent["addressing"] == "anyone"+ assert "room" not in doc and "kickoff" not in doc+ # The param asked only for an existing room is not part of this run.+ assert "existing_room" not in doc["params"]+++def test_new_room_names_the_agent_by_key_and_opens_it_to_that_room():+ compiled = compile_v2(EXPERT, {"start_in": "new_room"}, {"$creator": "ada"})+ doc = yaml.safe_load(compiled.document)+ assert doc["room"]["name"] == "Ask switch-expert"+ assert doc["room"]["agents"] == ["switch-expert"]+ assert doc["kickoff"] == "@switch-expert hi."+ assert compiled.room_addressing == {"switch-expert": ["Ask switch-expert"]}+ assert doc["agents"][0]["addressing"] == "owner"+++def test_existing_room_joins_the_one_picked():+ doc = _compiled({"start_in": "existing_room", "existing_room": "lobby"})+ assert doc["agents"][0]["join"] == ["{existing_room}"]+ assert doc["params"]["existing_room"]["type"] == "room"+ assert "room" not in doc+++def test_a_reference_to_a_resource_that_is_off_is_refused():+ text = EXPERT.replace('join: ["{existing_room}"]', 'join: ["{expert_room.name}"]')+ with pytest.raises(+ TemplateError, match="expert_room, which this run does not create"+ ):+ _compiled({}, text)+++def test_several_rooms_need_a_group_and_links_name_rooms_by_key():+ text = """\+version: 2+resources:+ team: { type: group, name: Team, links: [{from: lobby, to: work, label: next}] }+ lobby: { type: room, name: Lobby, description: d, group: team, kickoff: hi }+ work: { type: room, name: Work, description: d, group: team }+"""+ doc = _compiled({}, text)+ assert doc["group"] == {"name": "Team"}+ assert [r["name"] for r in doc["rooms"]] == ["Lobby", "Work"]+ assert doc["rooms"][0]["kickoff"] == "hi"+ assert doc["links"] == [{"from": "Lobby", "to": "Work", "label": "next"}]+ with pytest.raises(TemplateError, match="Several rooms go in a group"):+ _compiled(+ {},+ text.replace(+ " team: { type: group, name: Team, links: [{from: lobby, to: work, label: next}] }\n",+ "",+ ),+ )+++def test_kind_and_slots():+ assert template_kind(EXPERT) == "agent"+ (slot,) = agent_slots(EXPERT)+ assert (slot.key, slot.name, slot.machine) == ("expert", "{name}", "{machine}")+++def test_plan_resolves_the_machine_and_keeps_the_room_addressing():+ plan = plan_template(+ EXPERT,+ {},+ {"start_in": "new_room"},+ builtins={"$creator": "ada"},+ machines=MACHINES,+ )+ (agent,) = plan.new_agents+ assert (agent.name, agent.machine, agent.provider) == (+ "switch-expert",+ "m-laptop",+ "claude",+ )+ assert agent.directory == "{$agents_dir}/switch-expert"+ assert plan.room_addressing == {"switch-expert": ["Ask switch-expert"]}+ assert yaml.safe_load(plan.document or "")["room"]["agents"] == ["switch-expert"]+++def test_lint_reads_a_v2_document():+ assert lint_template(EXPERT).warnings == []+ broken = EXPERT.replace("type: room\n if:", "type: rom\n if:").replace(+ '"{start_in} == new_room"\n name', '"start_in == new_room"\n name'+ )+ codes = {f.code for f in lint_template(broken).errors}+ assert "invalid_resource_type" in codes+ unknown = lint_template(EXPERT.replace("{expert.name} hi", "{nobody.name} hi"))+ assert "unknown_reference" in {w.code for w in unknown.warnings}+++def test_an_input_that_refers_to_a_resource_is_resolved():+ plan = plan_template(+ EXPERT,+ {},+ {"name": "Expert N1", "directory": "{$agents_dir}/{expert.name}"},+ builtins={"$creator": "ada"},+ machines=MACHINES,+ )+ (agent,) = plan.new_agents+ assert agent.directory == "{$agents_dir}/expert-n1"+++def test_an_existing_room_to_join_comes_from_the_input():+ plan = plan_template(+ EXPERT,+ {},+ {"start_in": "existing_room", "existing_room": "gamma-room"},+ builtins={"$creator": "ada"},+ machines=MACHINES,+ )+ assert plan.new_agents[0].joins == ["gamma-room"]+++def test_an_existing_room_left_out_is_refused():+ from switch_core.template_runs import AgentsNotCreated++ with pytest.raises(AgentsNotCreated) as e:+ plan_template(+ EXPERT,+ {},+ {"start_in": "existing_room"},+ builtins={"$creator": "ada"},+ machines=MACHINES,+ )+ assert {p.code for p in e.value.problems} == {"input_missing"}diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.mdindex 608a6ee39..deea6043e 100644--- a/docs/TEMPLATES.md+++ b/docs/TEMPLATES.md@@ -23,9 +23,10 @@ root is the worked example, and `examples/` holds more.8. [Kickoff](#kickoff)9. [Where an agent works](#where-an-agent-works)10. [The form block](#the-form-block)-11. [Agents and saved templates](#agents-and-saved-templates)-12. [Validation](#validation)-13. [Versioning](#versioning)+11. [Version 2](#version-2)+12. [Agents and saved templates](#agents-and-saved-templates)+13. [Validation](#validation)+14. [Versioning](#versioning)## A first template@@ -43,9 +44,19 @@ params:type: providerdefault: [claude, codex, opencode]input: advanced+ location:+ type: location+ default: local+ input: advanced+ directory:+ type: directory+ default: "{$agents_dir}/{agent}"+ input: advancedagent:display_name: "{name}"provider: "{provider}"+ location: "{location}"+ directory: "{directory}"repo: https://github.com/jqlang/jqaddressing: anyoneinstructions: |@@ -60,9 +71,13 @@ kickoff: "@{agent} hi, introduce yourself in two lines."```The form for this template shows two inputs, the agent's name and the-messaging app, both filled in, and an Advanced fold with the provider. One-click creates the agent, then the room with the agent and the deployer in-it, then posts the kickoff.+messaging app, both filled in, and an Advanced fold with the provider, the+machine and the directory. One click creates the agent, then the room with+the agent and the deployer in it, then posts the kickoff.++Every agent a template creates must say what runs it, where, and in which+folder; the Console has no defaults of its own for them. See+[The agent block](#the-agent-block).## Document structure@@ -73,8 +88,8 @@ describe at least one thing to create.|---|---|---|| `version` | The format version, an integer. `1` today. | || `params` | The inputs of the form, each with a type and a policy. | |-| `agent` | One agent to create. | Switch Console |-| `agents` | A list of agents to create. | Switch Console |+| `agent` | One agent to create. | The server (a managed agent), or Switch Console |+| `agents` | A list of agents to create. | The server (managed agents), or Switch Console || `room` | One room to create. | The server || `group`, `rooms`, `links` | A room group, its rooms, and links between them. | The server || `kickoff` | A message posted into the room once it exists. | The server |@@ -85,13 +100,14 @@ room or group template by looking at which keys it has, so a saved documentwith `agents:` and `room:` is listed as a group. Nothing about the languagechanges with the kind.-Two engines read the document. Switch Console creates the agents, because an-agent runs on a machine the Console can reach and the server cannot, and-resolves the params only it can answer (where an agent runs, which coding-agent runs it, in which directory). The server creates the rooms from the-rest, through `POST /rooms/from-yaml`, and resolves the params that name-things it has (messaging apps, agents, rooms, users). Both read the same-document under the same rules.+Two engines read the document. Switch Console draws the form and resolves+the params only it can answer (a `location` on this computer or an SSH+host). The server creates the agents, as managed agents on the deployer's+machines, then the rooms, and resolves the params that name things it has+(machines, messaging apps, agents, rooms, users). On a server without agent+management the Console creates the agents itself and the server only the+rooms, through `POST /rooms/from-yaml`. Both read the same document under+the same rules.## Params@@ -131,9 +147,10 @@ is the name; keep it a plain identifier.| `bridge` | The display name of a messaging app set up on the server. | The server checks it exists. || `room` | The name of a room on the server. | The server checks it exists. || `user` | A username on the room's messaging app. | The server looks it up on the app. |-| `provider` | A coding agent id: `claude`, `codex` or `opencode`. | Switch Console; never sent to the server. |-| `location` | Where an agent runs: `local`, or an SSH host name the Console knows. | Switch Console; never sent to the server. |-| `directory` | An agent's working directory, on the machine it runs on. | Switch Console; never sent to the server. |+| `provider` | A coding agent id: `claude`, `codex` or `opencode`. | Read when the agents are created; never in the room document. |+| `location` | Where an agent runs: `local`, or an SSH host name the Console knows. | Switch Console; never in the room document. |+| `machine` | One of the deployer's machines on the server, by name or id. | Read when the agents are created; never in the room document. |+| `directory` | An agent's working directory, on the machine it runs on. | Read when the agents are created; never in the room document. |**`description`**. Data type: text. Shown under the input.@@ -201,15 +218,23 @@ param. Checked on the form and by the server.### What the form does with a param-The form has an agent section per agent the template creates, then a room-section. A param is shown in the section of the block that reads it: one-written into an agent's fields sits with that agent, one written into the-room sits with the room, and a `room` param always sits with the room since-it says where the agent works. A `provider`, `location` or `directory`-param that no agent binds applies to every agent.+The form lists the params in the order the document declares them, so the+author decides the order. The `ask` params come first; the `advanced` and+`fixed` ones sit together in one fold below them (see+[The form block](#the-form-block)), in the same order. A param that only the+room part reads is left out while the room is not being created, since it+does nothing then.-The Create button stays disabled while a required param is empty or a-value breaks its `pattern` or bounds, and says which.+Beside the inputs, a preview shows a card for every agent and room the+template creates. An agent's card shows the provider, machine and directory+it will get, as the inputs resolve them.++A `provider`, `location` or `directory` param that no agent's field reads+applies to every agent.++The Create button stays disabled while a required param is empty, a value+breaks its `pattern` or bounds, or an agent is missing its provider,+location or directory, and says which.## Placeholders and builtins@@ -237,23 +262,66 @@ offers to link it.```yamlagent:- name: identifier- display_name: text- description: text- instructions: text- provider: claude | codex | opencode | "{param}"- location: local | ssh host | "{param}"- directory: path | "{param}"- repo: URL- sources: [ {label, url} or url ]- addressing: owner | owner-agents | anyone- join: [ room name or "{param}" ]+ name: identifier+ display_name: text+ description: text+ instructions: text+ provider: claude | codex | opencode | "{param}"+ machine: machine name or id | "{param}"+ location: local | ssh host | "{param}"+ directory: path | "{param}"+ model: text | "{param}"+ advanced_config: { key: value }+ isolation: shared | isolated+ auto_approve: true | false+ connections: [ service, or {service, access, repos} ]+ repo: URL+ sources: [ {label, url} or url ]+ addressing: owner | owner-agents | anyone+ join: [ room name or "{param}" ]+ allow_existing: true | false````agents:` is a list of the same block, for a template that creates a team.In that form a room refers to each agent by the text written as its `name`-(`"{team}-triager"`), and the form lets the deployer point each entry at an-agent the server already has instead of creating it.+(`"{team}-triager"`).++**How agents are created.** On a server with agent management, every agent+a template creates is a *managed agent* of the deployer: Switch registers it+and places it on one of the deployer's machines, whose controller runs it.+The whole run goes to the server in one request (`POST /gateway/rooms/from-template`+from Switch Console, `run_template` from an agent), and the server checks it+whole before creating anything: each machine is the deployer's, online, with+the provider installed and signed in; each name is free; each connection is+the deployer's to grant; the room half is valid; and, when an agent runs+the template, its kickoff reaches the agents it mentions. A run that cannot+be done is refused with every problem and its reason code (such as+`controller_offline`, `provider_not_installed`, `provider_login_missing`,+`name_taken`, `connector_not_connected`), and nothing is created. When the+rooms then fail, the agents the run created are deleted again. An agent+running a template needs its owner's "can manage agents" capability. On a+server without agent management, Switch Console creates the agents itself,+on this computer or an SSH host, as before.++An entry with `allow_existing: true` lets the deployer fill it with an+agent the server already has instead of creating it: its card on the form+offers New agent or Existing agent. Without it the agent is always created,+and the form offers no such choice.++```yaml+agents:+ - name: "{team}-reviewer"+ allow_existing: true+ instructions: Review what the fixer opens.+```++**`provider`**, where it runs (**`machine`** or **`location`**) and+**`directory`** are required for every agent the template creates: each+written on the entry, literally or as a `{param}`, or through a param of+that type that no entry's field reads, which then applies to every agent.+Nothing fills in what the document does not say. A document missing one is+still saved, with a warning; the run refuses to create from it and names+what is missing.**`name`**. The identifier the agent is created under and addressed by:lowercase letters, digits, `.`, `-` and `_`, starting with a letter or@@ -267,26 +335,61 @@ to let the deployer change it.**`description`**. What the agent is for, shown to others.-**`instructions`**. The agent's brief. Required, except that the Console-reads the bundled Switch expert's from `AGENT.md` next to its template. A-template stored on a server or pasted into the Console carries it inline.+**`instructions`**. The agent's brief. Required. The Switch expert's source+in `switch-expert/` keeps it in `AGENT.md` next to the template; the server+writes it in when it serves the template.**`provider`**. The coding agent that runs it. A literal fixes it; `{param}`of type `provider` lets the template say how much choice the deployer has.-When the field is absent and no `provider` param is declared, the form asks,-with nothing selected: the Console never picks one on its own.-**`location`**. Where it runs. `local` is this computer; otherwise an SSH-host the Console knows. When absent and no `location` param is declared,-the agent runs on this computer.+**`machine`**. Where it runs, as one of the deployer's machines on the+server: its name or its id. A `machine` param offers the deployer a choice+among their machines; `default: [$first]` is the first online machine that+can run the agents' providers.-**`directory`**. Its working directory on that machine. `{$agents_dir}` and-`{agent}` are useful here. When absent and no `directory` param is declared,-the agent gets `{$agents_dir}/{agent}`, shown on the form under Advanced.+**`location`**. Where it runs, as Switch Console knows it: `local` is this+computer, otherwise an SSH host the Console knows. That is the Console's+idea, not the server's: on a server with agent management a location names+a machine only when it is the name or id of one of the deployer's machines+there, and otherwise the first online machine that can run the agent stands+in, as `$first` would. The form shows a `location` param as a choice among+the deployer's machines there. Without agent management, the Console runs+the agent on this computer or the SSH host, as before.-**`repo`**. A repository the agent works from. The Console clones it-(shallow) into the directory before the agent first runs; if that fails-the agent is still created and clones it itself.+**`directory`**. Its working directory on that machine. `{$agents_dir}` and+`{agent}` are useful here: `"{$agents_dir}/{agent}"` gives the agent a+folder of its own under the one its machine keeps agents in, which the+machine creates.++**`model`**. The model the provider runs. Absent, the provider's default.++**`advanced_config`**. The provider's advanced settings, keyed as Switch+Console's "Advanced configuration" (and `get_advanced_config`) lists them,+such as `{effort: high}`. Each value is checked against the provider's+setting.++**`isolation`**. `shared` (the default) runs the agent inside its machine's+controller; `isolated` runs it as a process of its own.++**`auto_approve`**. Whether the agent runs tools without asking for+approval. Default `false`.++**`connections`**. The deployer's own connections (GitHub, Atlassian, and+the rest of Settings, Connections) granted to the agent once it exists.+Each entry is a service name, or `{service, access, repos}`: `access` is+`read` (the default) or `write`, and `repos` lists the GitHub repositories,+as `owner/name`, a GitHub grant reaches; they must all be reachable through+one installation of the GitHub App. The deployer must have connected each+service, with write access to grant write, and connections must be on for+the server. The form shows each connection on the agent's card, and whether+the deployer has it.++**`repo`**. A repository the agent works from. A managed agent's+instructions tell it to clone the repository into its directory; it grants+nothing, so a private repository needs a `github` connection listing it, or+credentials on the machine. On a server without agent management, the+Console clones it (shallow) into the directory before the agent first runs;+if that fails the agent is still created and clones it itself.**`sources`**. Pages the agent should read. Shown to the deployer; the agentfetches them itself.@@ -296,7 +399,12 @@ deployer only; `owner-agents`, the deployer and their other agents;`anyone`, every member of its rooms. Set right after the agent is created.**`join`**. Rooms the agent is added to once it exists, by name or through-a `room` param. See the next section but one.+a `room` param. See the next section but one. Switch Console adds it after+the run; `run_template` refuses a `join`.++**`allow_existing`**. Data type: boolean. Default: `false`. Whether the+deployer may use an agent the server already has for this entry instead of+creating it.## The room block@@ -415,9 +523,10 @@ param resolves to `$new`. A document with neither `room:` nor `join:`creates the agent and stops.On the form, a `room` param an agent joins is a switch with the param's-label, on when its chain resolved to a room and off otherwise. The room-choice and the room's own params (its messaging app, its members) sit-under the switch and only while it is on. With `required: false` and no+label, in its declared place, on when its chain resolved to a room and off+otherwise. The room choice sits under the switch, only while it is on. The+room's own params (its messaging app, its members) are shown only while the+template's room is the one being created. With `required: false` and nodefault the switch starts off, and turning it on offers the template'sroom first; the Switch expert ships that way. With `default: [$new]` itstarts on.@@ -439,15 +548,101 @@ form:open: false```-Every `input: advanced` and `input: fixed` param of an agent, and the-agent's directory when the template names none, sit together in one fold-under the agent's asked inputs. `label` names the fold; `open` says whether-it starts open. Folded, it shows its values on one line with a Change+Every `input: advanced` and `input: fixed` param sits in one fold below+the asked inputs, in declaration order. `label` names the fold; `open` says+whether it starts open. Folded, it shows its values on one line with a Changebutton, and it opens by itself when something inside it is empty or wrong.The block is the Console's; the server ignores it.+## Version 2++`version: 2` writes a template as resources, each with a key and a type,+instead of blocks whose meaning comes from where they sit. Version 1+documents keep working unchanged. A version 2 template creates managed+agents, so it needs a server that runs agent management.+The Switch expert, `switch-expert/template.yaml`, is a complete one;+`examples/agent-templates/switch-expert.v2.template.yaml` is the same with its+instructions inline, to paste into the Use page.++```yaml+version: 2+params:+ start_in: { type: enum, enum: [nowhere, new_room, existing_room], default: nowhere }+ existing_room: { type: room, if: "{start_in} == existing_room" }+ machine: { type: machine, default: [$first], input: advanced }+resources:+ expert:+ type: agent+ display_name: Switch expert+ instructions: Answer questions about Switch.+ provider: claude+ machine: "{machine}"+ directory: "{$agents_dir}/{expert.name}"+ join: ["{existing_room}"]+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ agents: [expert]+ kickoff: "@{expert.name} hi."+```++**Resources.** `resources:` maps each key (letters, digits, `_`) to a+resource with a `type`: `agent` (the fields of [The agent block](#the-agent-block)),+`room` (the fields of [The room block](#the-room-block), plus its own+`kickoff:` and, inside a group, `group: <key>`), or `group` (`name`,+`description`, `color`, and `links: [{from: room key, to: room key, label}]`).+Several rooms go in one group.++**References.** A resource names another by its key: a room's `agents:` and+`aliases:` take agent keys (or names of agents that already exist), and+`{key.name}` anywhere is the name that resource is created under: an agent's+`name`, or the identifier derived from its `display_name`. A reference to a+resource whose `if:` does not hold is refused.++**`if:`.** The one conditional, and its only forms are `"{param}"` (true when+the value is) and `"{param} == value"` / `"{param} != value"`:++- On a resource: it is created only while the condition holds.+- On a param: it is asked only while the condition holds. A param that is not+ asked reads as empty, and drops out of the lists it was written in.+- In a field's value, written as a list of `{if, value}`: the first whose+ condition holds is taken; an entry with no `if` always holds.++The form asks a param while its `if:` holds and while something that is made+reads it, so the messaging app is not asked when the room it is for is off.++**Addressing.** Besides `owner`, `owner-agents` and `anyone`, an agent's+`addressing` may be `{anyone_in: [room keys]}`: its owner, and anyone in+those rooms of the run, set once the rooms exist.++**`join`.** Rooms that already exist, by name, the agent is added to once it+is created. The server checks each exists and that the deployer may add+agents to it, before creating anything.++**Running.** The server works the run out from the document and the inputs:+which resources the conditions make, each agent's machine and provider, and+the rest as for any template. Switch Console sends the document whole+(`POST /gateway/rooms/from-template-document`), and `run_template` takes it+as any saved template; `agents: {resource key: existing agent}` fills a slot+whose agent says `allow_existing: true`.+## Agents and saved templates+Every template lives on the server. Besides the ones people and agents save+on a workspace, the server serves the official templates that come with+Switch, under `official:` ids (`official:switch-expert`), first in every+listing, to people and agents alike. Their source is in the repository+(`core/switch_core/official_templates/`, the Switch expert copied from+`switch-expert/`); where a template has a version for servers without agent+management, the `agent_management` feature flag picks which one is served.+Nobody can change or delete an official template: save a copy under another+name to change it.+Agents can use the templates saved on a workspace through their Switchtools: `list_templates`, `get_template`, `run_template`, `save_template`,`update_template` and `delete_template`. `get_template_guide` gives an agent@@ -458,14 +653,20 @@ documents against (`core/switch_core/template_guide.py`; keep it in step).ones. An owner's admin rights do not carry over to their agents.- **Running.** A room or group template runs the way it does from theConsole, through the same checks as an agent's own rooms (see- [Kickoff](#kickoff)). An agent cannot create agents, so an agent or team- template runs only when every agent it describes is replaced by one that- already exists: `run_template` takes `agents: {slot: existing agent}`,- and `get_template` lists the slots. The `agent:`/`agents:` block and the- Console-only params are dropped, and the room half runs.+ [Kickoff](#kickoff)). An agent or team template creates its agents as+ managed agents of the agent's owner, on the machines the entries name,+ then the rooms (see [The agent block](#the-agent-block)); the agent needs+ its owner's "can manage agents" capability. `get_template` lists each+ slot with its machine, provider, model, connections and whether an+ existing agent may stand in; `run_template` takes+ `agents: {slot: existing agent}` for the slots that allow one.- **Saving.** An agent saves for its owner, `private` or `shared` (everyonereads it, only the saver changes it), and the template records which- agent saved it. A name the owner already uses is refused.+ agent saved it. A name the owner already uses is refused. A document with+ warnings, an agent with no provider for example, is refused and the+ warnings listed, so the agent can fix them or advise whoever asked;+ `bypass_warnings: true` saves it anyway and returns the warnings.+ `update_template` does the same for a new document.- **Changing and deleting.** Only the agent that saved a template may changeor delete it; not its owner's templates, and not another agent's.@@ -480,7 +681,16 @@ document outright: not YAML, empty, or not a mapping. Everything else is awarning or an error the deployer sees against the field: an unknown paramtype, a default that is not one of the enum's choices, a `$new` in adocument with no room, a placeholder no param declares, a param nothing-uses.+uses, an agent whose provider, location or directory the document never+says.++Completeness is warned about on save and enforced on run. A registry keeps+documents written for other versions of the format, so the registry never+refuses one for what it leaves out; the form, which knows exactly what this+Console needs, refuses to create from it and names what is missing. An+agent saving through its Switch tools is stopped at the warnings first and+saves past them with `bypass_warnings`, so it knows before it stores a+template nobody can use yet.A param field this server does not know is a warning, not an error, since aregistry holds documents written for newer versions of Switch than the one@@ -488,6 +698,6 @@ reading them.## Versioning-`version: 1` names the format described here. The key is accepted and-checked as an integer; the server does not yet change how it reads a-document by its version, and a document without one is read the same way.+`version: 1` names the format described above; a document without a version+is read the same way. `version: 2` (or a document with `resources:`) is read+as described in [Version 2](#version-2).diff --git a/examples/agent-templates/jq-expert.template.yaml b/examples/agent-templates/jq-expert.template.yamlindex f4dbc3104..46b823b8a 100644--- a/examples/agent-templates/jq-expert.template.yaml+++ b/examples/agent-templates/jq-expert.template.yaml@@ -5,8 +5,27 @@# server or pasted into the Console. Save it to a workspace with kind# `agent`, or paste it into the Console's import page.version: 1+params:+ provider:+ type: provider+ description: The coding agent that runs it. The first one installed is chosen.+ default: [claude, codex, opencode]+ input: advanced+ location:+ type: location+ description: The machine it runs on.+ default: local+ input: advanced+ directory:+ type: directory+ description: Its working directory. The jq repository is cloned inside it.+ default: "{$agents_dir}/{agent}"+ input: advancedagent:name: jq-expert+ provider: "{provider}"+ location: "{location}"+ directory: "{directory}"description: >-Answers questions about jq, the command-line JSON processor, and writesand debugs jq filters. Reads the jq source and manual rather thandiff --git a/examples/agent-templates/support-desk.template.yaml b/examples/agent-templates/support-desk.template.yamlindex c45ff4e9c..9029bd6b1 100644--- a/examples/agent-templates/support-desk.template.yaml+++ b/examples/agent-templates/support-desk.template.yaml@@ -16,6 +16,16 @@ params:description: Which coding agent backs both. The first one installed is chosen.default: [claude, codex, opencode]input: advanced+ location:+ type: location+ description: The machine both run on.+ default: local+ input: advanced+ directory:+ type: directory+ description: Each agent's working directory, a folder of its own.+ default: "{$agents_dir}/{agent}"+ input: advancedbridge:type: bridgedescription: Where the rooms are mirrored. The server's default app is chosen.@@ -26,6 +36,8 @@ agents:description: Meets every request first and answers what it canaddressing: anyoneprovider: "{provider}"+ location: "{location}"+ directory: "{directory}"instructions: |You are the greeter of a support desk. You sit in two rooms: the intakeroom, where people bring requests, and the escalations room, where the@@ -42,6 +54,8 @@ agents:description: Works the cases the greeter escalatesaddressing: owner-agentsprovider: "{provider}"+ location: "{location}"+ directory: "{directory}"instructions: |You are the engineer of a support desk. You only see what the greeterescalates into your room. For each case: say what you are about todiff --git a/examples/agent-templates/switch-expert.v2.template.yaml b/examples/agent-templates/switch-expert.v2.template.yamlnew file mode 100644index 000000000..d5b1aa218--- /dev/null+++ b/examples/agent-templates/switch-expert.v2.template.yaml@@ -0,0 +1,91 @@+# The Switch expert in version 2 of the template language: every resource has+# a key and a type, resources refer to each other by key, and `if:` is the one+# conditional. docs/TEMPLATES.md, "Version 2", describes the language.+version: 2+params:+ name:+ type: string+ label: Agent name+ description: How the agent is shown to people. It is addressed by a short form of this.+ default: Switch expert+ start_in:+ type: enum+ enum: [nowhere, new_room, existing_room]+ label: Start it in+ description: Nowhere creates the agent alone; add it to rooms later.+ default: nowhere+ existing_room:+ type: room+ label: Which room+ if: "{start_in} == existing_room"+ bridge:+ type: bridge+ label: Messaging app+ description: Where the new room is created. Slack when it is set up, else the server's default app.+ default: [Slack, $first]+ required: false+ provider:+ type: provider+ description: The coding agent that runs it. The first one ready on its machine is chosen.+ default: [claude, codex, opencode]+ input: advanced+ machine:+ type: machine+ description: The machine it runs on. The first online one that can run it, unless you pick.+ default: [$first]+ input: advanced+ directory:+ type: directory+ description: Its working directory. The repository is cloned inside it.+ default: "{$agents_dir}/{expert.name}"+ input: advanced+form:+ advanced: { label: Advanced, open: false }++resources:+ expert:+ type: agent+ display_name: "{name}"+ description: >-+ Answers questions about Switch and helps you design and build things with+ it, grounded in a local clone of the Switch repository.+ instructions: |+ You answer questions about Switch and help people design and build things+ with it. Read the Switch repository in your working directory rather than+ answering from memory, and say where in it the answer lives.+ provider: "{provider}"+ machine: "{machine}"+ directory: "{directory}"+ repo: https://github.com/sandbox-quantum/switch+ join: ["{existing_room}"]+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ sources:+ - { label: Stand up a Switch expert, url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert }+ - { label: Switch documentation, url: https://docs.switchagents.ai/switch-rooms/getting-started }++ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ description: >-+ Where {$creator} asks {expert.name} about Switch: how it works, how to set+ something up, why something is not behaving.+ channel_type: channel_private+ bridge: "{bridge}"+ agents: [expert]+ # You join the room on its messaging app; a server with none has nobody+ # to invite.+ users:+ - if: "{bridge}"+ value: ["{$creator}"]+ - value: []+ instructions: |+ This room is for asking {expert.name} about Switch. Answer here, briefly+ and concretely. When you do not know, say so and say where the answer+ would live.+ kickoff: |+ @{expert.name} hi. Introduce yourself in two lines, then tell me the first+ thing you would check if an agent in a room stopped answering.diff --git a/examples/agent-templates/triage-pair.template.yaml b/examples/agent-templates/triage-pair.template.yamlindex 9cdf3e597..abb55a7ef 100644--- a/examples/agent-templates/triage-pair.template.yaml+++ b/examples/agent-templates/triage-pair.template.yaml@@ -22,6 +22,11 @@ params:description: The machine both run on.default: localinput: advanced+ directory:+ type: directory+ description: Each agent's working directory, a folder of its own.+ default: "{$agents_dir}/{agent}"+ input: advancedbridge:type: bridgedescription: Where the room is mirrored. The server's default app is chosen.@@ -33,6 +38,7 @@ agents:addressing: anyoneprovider: "{provider}"location: "{location}"+ directory: "{directory}"instructions: |You are the triager of a small team. Reports arrive in your room frompeople and from other agents. For each one:@@ -50,6 +56,7 @@ agents:addressing: owner-agentsprovider: "{provider}"location: "{location}"+ directory: "{directory}"instructions: |You reproduce bugs the triager hands you. For each one, work in yourdirectory: write the smallest script or command that shows thediff --git a/gateway/src/data/api.ts b/gateway/src/data/api.tsindex 80e0befe4..336d892d4 100644--- a/gateway/src/data/api.ts+++ b/gateway/src/data/api.ts@@ -1900,8 +1900,11 @@ export async function detachPackageFromRoom(export interface TemplateSummary {id: string;- owner_id: string;+ /** Null for a template that comes with Switch. */+ owner_id: string | null;owner_name: string | null;+ /** Comes with Switch: on every workspace, and changed by nobody. */+ official: boolean;name: string;description: string;kind: string;diff --git a/gateway/src/pages/resources/TemplatesTab.tsx b/gateway/src/pages/resources/TemplatesTab.tsxindex 0fe8bb71f..892054416 100644--- a/gateway/src/pages/resources/TemplatesTab.tsx+++ b/gateway/src/pages/resources/TemplatesTab.tsx@@ -46,7 +46,8 @@ export default function TemplatesTab({ refreshKey }: Props) {const owners = useMemo(() => {const m = new Map<string, string>();for (const t of catalogue ?? []) {- m.set(t.owner_id, t.owner_name ?? t.owner_id);+ // A template that comes with Switch has no owner to filter by.+ if (t.owner_id !== null) m.set(t.owner_id, t.owner_name ?? t.owner_id);}return [...m.entries()].map(([id, name]) => ({ id, name }));}, [catalogue]);diff --git a/switch-expert/README.md b/switch-expert/README.mdindex 771ffe421..19090a75b 100644--- a/switch-expert/README.md+++ b/switch-expert/README.md@@ -13,12 +13,12 @@ Use **Switch Console**. It creates the agent, gives it its identity and credentiholds its instructions — an agent set up outside it does not connect to Switch properly.**The short way: the template.** Open **Templates** in Switch Console, pick **Switch-expert**, choose the provider it runs on, and click **Add agent and open its room**. The-Console fills in the name, description and instructions from this folder, creates a-working directory for it with this repository cloned inside, puts it in a room with you,-and says hello so it starts answering. That is the whole setup. The template is-[`template.yaml`](template.yaml); it is also the worked example of the agent template-format.+expert**, choose where it starts (on its own, in a new room made for it, or in a room+you pick), and click Create. The server creates it on one of your machines (the first+online one that can run it, unless you choose under Advanced), with this repository to+clone into its working directory, and, for a new room, puts it there with you and says+hello so it starts answering. It needs a server that runs agent management. The template+is [`template.yaml`](template.yaml), written in version 2 of the template format.**The long way, by hand:**diff --git a/switch-expert/template.console.yaml b/switch-expert/template.console.yamlnew file mode 100644index 000000000..50dbde3a1--- /dev/null+++ b/switch-expert/template.console.yaml@@ -0,0 +1,132 @@+# Switch expert, as a template, for a server that runs no agent management:+# Switch Console creates the agent itself, on this computer or an SSH host.+# Where the server runs agent management, template.yaml (version 2) is used+# instead. Switch Console picks between them by the server's agent_management+# feature flag.+#+# A template is one YAML document that describes what to create: an agent,+# a room, or several of each. Switch Console reads it on its Templates page,+# shows one form built from the `params:` block, and creates everything in+# one pass. The language is documented in docs/TEMPLATES.md at the+# repository root; this header is the short version.+#+# params: What the form asks for, referred to as `{name}` anywhere+# below. Each param says what it is (`type`), what it starts+# as (`default`, one value or a list of candidates tried in+# order, `$first` meaning the first one the server has),+# whether it may be left empty (`required`), and how the+# form shows it (`input`: `ask` for a visible input,+# `advanced` for one folded away with its default filled in,+# `fixed` for a value the deployer cannot change). Nothing+# the form fills in comes from anywhere else: every default+# is written here.+#+# agent: Who the agent is. `display_name` is how the agent is+# shown to people; the identifier it is addressed by+# (`name`) is derived from it unless written. `provider`,+# `location` and `directory` say what runs it, where, and+# in which folder, each read from a param so the template+# decides what the deployer may change. `repo` is the+# repository it works from: Switch Console clones it+# (shallow) into the agent's directory before the agent+# first runs, and the agent clones it itself when that did+# not happen. `sources` are the pages it should read.+# `addressing` is who may talk to it: `owner` (the default),+# `owner-agents`, or `anyone`. `join` lists rooms it is put+# in once it exists, by name or through a `room` param; a+# `room` param whose default lists `$new` offers the room+# below as one of the choices. `instructions` is its brief,+# read from AGENT.md next to this file for the bundled copy.+#+# room: The room to put the agent in as soon as it exists, in the+# shape of a room template. `{agent}` is the agent's+# identifier; `{$creator}` is the deployer. Without a+# `room:` the template creates the agent and stops.+#+# kickoff: Posted into the room on behalf of the deployer once the+# room exists. An agent starts working when a message+# addresses it, so mention the agent here or it will sit in+# the room without answering.+#+# form: How the form folds things away: `advanced.label` names the+# fold that holds the `input: advanced` and `input: fixed`+# params, `advanced.open` says whether it starts open.+#+# The form for this template shows the agent's name, filled in, an Advanced+# fold with the provider, where it runs and its directory, and one switch,+# "Start it in a room", off by default. One click creates the agent alone;+# switched on, the room below is the choice, with Slack as the messaging+# app when it is set up, and the agent starts there.+version: 1+params:+ name:+ type: string+ label: Agent name+ description: How the agent is shown to people. It is addressed by a short form of this.+ default: Switch expert+ required: true+ where:+ type: room+ label: Start it in a room+ description: >-+ Off, the agent is created on its own and you add it to rooms later. On,+ it starts in a new room made for it, or in one you pick.+ required: false+ bridge:+ type: bridge+ label: Messaging app+ description: Where the new room is created. Slack when it is set up, else the server's default app.+ default: [Slack, $first]+ required: false+ provider:+ type: provider+ description: The coding agent that runs it. The first one installed where it runs is chosen.+ default: [claude, codex, opencode]+ input: advanced+ location:+ type: location+ description: The machine it runs on.+ default: local+ input: advanced+ directory:+ type: directory+ description: Its working directory. The repository is cloned inside it.+ default: "{$agents_dir}/{agent}"+ input: advanced+form:+ advanced:+ label: Advanced+ open: false+agent:+ display_name: "{name}"+ description: >-+ Answers questions about Switch and helps you design and build things with+ it. Grounded in a local clone of the Switch repository, which it re-reads+ rather than answering from memory.+ provider: "{provider}"+ location: "{location}"+ directory: "{directory}"+ join: ["{where}"]+ repo: https://github.com/sandbox-quantum/switch+ addressing: anyone+ sources:+ - label: Stand up a Switch expert+ url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert+ - label: Switch documentation+ url: https://docs.switchagents.ai/switch-rooms/getting-started+room:+ name: "Ask {agent}"+ description: >-+ Where {$creator} asks {agent} about Switch: how it works, how to set+ something up, why something is not behaving.+ channel_type: channel_private+ bridge: "{bridge}"+ agents: ["{agent}"]+ users: ["{$creator}"]+ instructions: |+ This room is for asking {agent} about Switch. Answer here, briefly and+ concretely, in the plainest words that are still true. When you do not+ know, say so and say where the answer would live.+kickoff: |+ @{agent} hi. Introduce yourself in two lines, then tell me the first thing+ you would check if an agent in a room stopped answering.diff --git a/switch-expert/template.yaml b/switch-expert/template.yamlindex 91d938063..b3497ade5 100644--- a/switch-expert/template.yaml+++ b/switch-expert/template.yaml@@ -1,73 +1,41 @@# Switch expert, as a template.#-# A template is one YAML document that describes what to create: an agent,-# a room, or several of each. Switch Console reads it on its Templates page,-# shows one form built from the `params:` block, and creates everything in-# one pass. The language is documented in docs/TEMPLATES.md at the-# repository root; this header is the short version.+# A template is one YAML document that describes what to create. Switch Console+# reads it on its Templates page, shows one form built from `params:`, and the+# server creates everything in one pass. This one is written in version 2 of+# the language, documented in docs/TEMPLATES.md ("Version 2"):#-# params: What the form asks for, referred to as `{name}` anywhere-# below. Each param says what it is (`type`), what it starts-# as (`default`, one value or a list of candidates tried in-# order, `$first` meaning the first one the server has),-# whether it may be left empty (`required`), and how the-# form shows it (`input`: `ask` for a visible input,-# `advanced` for one folded away with its default filled in,-# `fixed` for a value the deployer cannot change). Nothing-# the form fills in comes from anywhere else: every default-# is written here.+# params: What the form asks for, referred to as `{name}` below. Each says+# its type, its default (a list of candidates is tried in order,+# `$first` meaning the first one that works), and how the form+# shows it (`input: advanced` folds it away). An `if:` asks it+# only while the condition holds.#-# agent: Who the agent is. `display_name` is how the agent is-# shown to people; the identifier it is addressed by-# (`name`) is derived from it unless written. `provider`,-# `location` and `directory` say what runs it, where, and-# in which folder, each read from a param so the template-# decides what the deployer may change. `repo` is the-# repository it works from: Switch Console clones it-# (shallow) into the agent's directory before the agent-# first runs, and the agent clones it itself when that did-# not happen. `sources` are the pages it should read.-# `addressing` is who may talk to it: `owner` (the default),-# `owner-agents`, or `anyone`. `join` lists rooms it is put-# in once it exists, by name or through a `room` param; a-# `room` param whose default lists `$new` offers the room-# below as one of the choices. `instructions` is its brief,-# read from AGENT.md next to this file for the bundled copy.+# resources: What the template creates, each under a key with a `type`:+# `expert`, the agent, and `expert_room`, the room it starts in.+# Resources name each other by key (`agents: [expert]`), and+# `{expert.name}` is the name the agent is created under. The+# room's `if:` makes it only when you choose New room.#-# room: The room to put the agent in as soon as it exists, in the-# shape of a room template. `{agent}` is the agent's-# identifier; `{$creator}` is the deployer. Without a-# `room:` the template creates the agent and stops.-#-# kickoff: Posted into the room on behalf of the deployer once the-# room exists. An agent starts working when a message-# addresses it, so mention the agent here or it will sit in-# the room without answering.-#-# form: How the form folds things away: `advanced.label` names the-# fold that holds the `input: advanced` and `input: fixed`-# params, `advanced.open` says whether it starts open.-#-# The form for this template shows the agent's name, filled in, an Advanced-# fold with the provider, where it runs and its directory, and one switch,-# "Start it in a room", off by default. One click creates the agent alone;-# switched on, the room below is the choice, with Slack as the messaging-# app when it is set up, and the agent starts there.-version: 1+# The agent's instructions are AGENT.md, next to this file: the Console puts+# them into the document before it is sent or saved.+version: 2params:name:type: stringlabel: Agent namedescription: How the agent is shown to people. It is addressed by a short form of this.default: Switch expert- required: true- where:+ start_in:+ type: enum+ enum: [nowhere, new_room, existing_room]+ label: Start it in+ description: Nowhere creates the agent alone; add it to rooms later.+ default: nowhere+ existing_room:type: room- label: Start it in a room- description: >-- Off, the agent is created on its own and you add it to rooms later. On,- it starts in a new room made for it, or in one you pick.- required: false+ label: Which room+ if: "{start_in} == existing_room"bridge:type: bridgelabel: Messaging app@@ -76,53 +44,62 @@ params:required: falseprovider:type: provider- description: The coding agent that runs it. The first one installed where it runs is chosen.+ description: The coding agent that runs it. The first one ready on its machine is chosen.default: [claude, codex, opencode]input: advanced- location:- type: location- description: The machine it runs on.- default: local+ machine:+ type: machine+ description: The machine it runs on. The first online one that can run it, unless you pick.+ default: [$first]input: advanceddirectory:type: directorydescription: Its working directory. The repository is cloned inside it.- default: "{$agents_dir}/{agent}"+ default: "{$agents_dir}/{expert.name}"input: advancedform:- advanced:- label: Advanced- open: false-agent:- display_name: "{name}"- description: >-- Answers questions about Switch and helps you design and build things with- it. Grounded in a local clone of the Switch repository, which it re-reads- rather than answering from memory.- provider: "{provider}"- location: "{location}"- directory: "{directory}"- join: ["{where}"]- repo: https://github.com/sandbox-quantum/switch- addressing: anyone- sources:- - label: Stand up a Switch expert- url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert- - label: Switch documentation- url: https://docs.switchagents.ai/switch-rooms/getting-started-room:- name: "Ask {agent}"- description: >-- Where {$creator} asks {agent} about Switch: how it works, how to set- something up, why something is not behaving.- channel_type: channel_private- bridge: "{bridge}"- agents: ["{agent}"]- users: ["{$creator}"]- instructions: |- This room is for asking {agent} about Switch. Answer here, briefly and- concretely, in the plainest words that are still true. When you do not- know, say so and say where the answer would live.-kickoff: |- @{agent} hi. Introduce yourself in two lines, then tell me the first thing- you would check if an agent in a room stopped answering.+ advanced: { label: Advanced, open: false }++resources:+ expert:+ type: agent+ display_name: "{name}"+ description: >-+ Answers questions about Switch and helps you design and build things with+ it, grounded in a local clone of the Switch repository.+ provider: "{provider}"+ machine: "{machine}"+ directory: "{directory}"+ repo: https://github.com/sandbox-quantum/switch+ join: ["{existing_room}"]+ addressing:+ - if: "{start_in} == new_room"+ value: { anyone_in: [expert_room] }+ - value: anyone+ sources:+ - { label: Stand up a Switch expert, url: https://docs.switchagents.ai/switch-rooms/getting-started/switch-expert }+ - { label: Switch documentation, url: https://docs.switchagents.ai/switch-rooms/getting-started }++ expert_room:+ type: room+ if: "{start_in} == new_room"+ name: "Ask {expert.name}"+ description: >-+ Where {$creator} asks {expert.name} about Switch: how it works, how to set+ something up, why something is not behaving.+ channel_type: channel_private+ bridge: "{bridge}"+ agents: [expert]+ # You join the room on its messaging app; a server with none has nobody+ # to invite.+ users:+ - if: "{bridge}"+ value: ["{$creator}"]+ - value: []+ instructions: |+ This room is for asking {expert.name} about Switch. Answer here, briefly+ and concretely. When you do not know, say so and say where the answer+ would live.+ kickoff: |+ @{expert.name} hi. Introduce yourself in two lines, then tell me the first+ thing you would check if an agent in a room stopped answering.