diff --git a/packages/ai-bot/README.md b/packages/ai-bot/README.md
index c90213cd2b..9c39e91744 100644
--- a/packages/ai-bot/README.md
+++ b/packages/ai-bot/README.md
@@ -42,7 +42,7 @@ It will be able to see any cards shared in the chat and can respond using GPT4 i
 You can deliberately trigger a specific patch by sending a message that starts `debug:patch:` and has the JSON patch you want returned. For example:
 
 ```
-debug:patch:{"card_id":"http://localhost:4200/experiments/Author/1", "description": "message", "attributes": {"firstName": "David"}}
+debug:patch:{"attributes": {"cardId":"http://localhost:4200/experiments/Author/1", "patch": { "attributes": {"firstName": "David"}}}}
 ```
 
 This will return a patch with the ID of the last card you uploaded. This does not hit GPT4 and is useful for testing the integration of the two components without waiting for streaming responses.
diff --git a/packages/ai-bot/helpers.ts b/packages/ai-bot/helpers.ts
index d6907ef583..5ac0211855 100644
--- a/packages/ai-bot/helpers.ts
+++ b/packages/ai-bot/helpers.ts
@@ -246,6 +246,7 @@ export function getTools(
   history: DiscreteMatrixEvent[],
   aiBotUserId: string,
 ): Tool[] {
+  // TODO: there should be no default tools defined in the ai-bot, tools must be determined by the host
   let searchTool = getSearchTool();
   let tools = [searchTool];
   // Just get the users messages
@@ -426,7 +427,6 @@ export function getModifyPrompt(
     mostRecentlyAttachedCard,
     attachedCards,
   );
-
   if (skillCards.length) {
     systemMessage += SKILL_INSTRUCTIONS_MESSAGE;
     systemMessage += skillCardsToMessage(skillCards);
diff --git a/packages/ai-bot/lib/debug.ts b/packages/ai-bot/lib/debug.ts
index c1019a5b55..b833d74d9e 100644
--- a/packages/ai-bot/lib/debug.ts
+++ b/packages/ai-bot/lib/debug.ts
@@ -33,16 +33,21 @@ export async function handleDebugCommands(
     let patchMessage = eventBody.split('debug:patch:')[1];
     // If there's a card attached, we need to split it off to parse the json
     patchMessage = patchMessage.split('(Card')[0];
-    let command: {
-      card_id?: string;
+    let toolArguments: {
+      attributes?: {
+        cardId?: string;
+        patch?: any;
+      };
       description?: string;
-      attributes?: any;
     } = {};
     try {
-      command = JSON.parse(patchMessage);
-      if (!command.card_id || !command.description || !command.attributes) {
+      toolArguments = JSON.parse(patchMessage);
+      if (
+        !toolArguments.attributes?.cardId ||
+        !toolArguments.attributes?.patch
+      ) {
         throw new Error(
-          'Invalid debug patch: card_id, description, or attributes is missing.',
+          'Invalid debug patch: attributes.cardId, or attributes.patch is missing.',
         );
       }
     } catch (error) {
@@ -54,7 +59,17 @@ export async function handleDebugCommands(
         undefined,
       );
     }
-    return await sendOption(client, roomId, command, undefined);
+    return await sendOption(
+      client,
+      roomId,
+      {
+        id: 'patchCard-debug',
+        name: 'patchCard',
+        type: 'function',
+        arguments: toolArguments,
+      },
+      undefined,
+    );
   }
   return;
 }
diff --git a/packages/ai-bot/main.ts b/packages/ai-bot/main.ts
index 910a3851ee..6431c8a378 100644
--- a/packages/ai-bot/main.ts
+++ b/packages/ai-bot/main.ts
@@ -44,16 +44,17 @@ class Assistant {
   getResponse(history: DiscreteMatrixEvent[]) {
     let tools = getTools(history, this.id);
     let messages = getModifyPrompt(history, this.id, tools);
+
     if (tools.length === 0) {
       return this.openai.beta.chat.completions.stream({
         model: 'openai/gpt-4o',
-        messages: messages,
+        messages,
       });
     } else {
       return this.openai.beta.chat.completions.stream({
         model: 'openai/gpt-4o',
-        messages: messages,
-        tools: tools,
+        messages,
+        tools,
         tool_choice: 'auto',
       });
     }
diff --git a/packages/ai-bot/tests/chat-titling-test.ts b/packages/ai-bot/tests/chat-titling-test.ts
index 910208e7c0..87e8beda2f 100644
--- a/packages/ai-bot/tests/chat-titling-test.ts
+++ b/packages/ai-bot/tests/chat-titling-test.ts
@@ -378,9 +378,13 @@ module('shouldSetRoomTitle', () => {
             toolCall: {
               name: 'patchCard',
               arguments: {
-                card_id: 'http://localhost:4201/experiments/Friend/1',
                 attributes: {
-                  firstName: 'Dave',
+                  cardId: 'http://localhost:4201/experiments/Friend/1',
+                  patch: {
+                    attributes: {
+                      firstName: 'Dave',
+                    },
+                  },
                 },
               },
             },
@@ -443,9 +447,13 @@ module('shouldSetRoomTitle', () => {
             toolCall: {
               name: 'patchCard',
               arguments: {
-                card_id: 'http://localhost:4201/drafts/Friend/1',
                 attributes: {
-                  firstName: 'Dave',
+                  cardId: 'http://localhost:4201/drafts/Friend/1',
+                  patch: {
+                    attributes: {
+                      firstName: 'Dave',
+                    },
+                  },
                 },
               },
             },
diff --git a/packages/ai-bot/tests/prompt-construction-test.ts b/packages/ai-bot/tests/prompt-construction-test.ts
index 9d1a0c3190..9a236a60f9 100644
--- a/packages/ai-bot/tests/prompt-construction-test.ts
+++ b/packages/ai-bot/tests/prompt-construction-test.ts
@@ -15,7 +15,7 @@ import type {
   Tool,
   CardMessageContent,
 } from 'https://cardstack.com/base/matrix-event';
-import { EventStatus } from 'matrix-js-sdk';
+import { EventStatus, IRoomEvent } from 'matrix-js-sdk';
 import type { SingleCardDocument } from '@cardstack/runtime-common';
 import { CardDef } from 'https://cardstack.com/base/card-api';
 
@@ -769,7 +769,9 @@ module('getModifyPrompt', () => {
               openCardIds: ['http://localhost:4201/experiments/Friend/1'],
               tools: [
                 getPatchTool('http://localhost:4201/experiments/Friend/1', {
-                  firstName: { type: 'string' },
+                  attributes: {
+                    firstName: { type: 'string' },
+                  },
                 }),
               ],
               submode: 'interact',
@@ -891,13 +893,13 @@ module('getModifyPrompt', () => {
         parameters: {
           type: 'object',
           properties: {
-            description: {
-              type: 'string',
-            },
             card_id: {
               type: 'string',
               const: 'http://localhost:4201/experiments/Friend/1',
             },
+            description: {
+              type: 'string',
+            },
             attributes: {
               type: 'object',
               properties: {
@@ -928,7 +930,12 @@ module('getModifyPrompt', () => {
               openCardIds: ['http://localhost:4201/experiments/Friend/1'],
               tools: [
                 getPatchTool('http://localhost:4201/experiments/Friend/1', {
-                  firstName: { type: 'string' },
+                  attributes: {
+                    type: 'object',
+                    properties: {
+                      firstName: { type: 'string' },
+                    },
+                  },
                 }),
               ],
               submode: 'interact',
@@ -960,15 +967,30 @@ module('getModifyPrompt', () => {
             description: {
               type: 'string',
             },
-            card_id: {
-              type: 'string',
-              const: 'http://localhost:4201/experiments/Friend/1',
-            },
-            firstName: {
-              type: 'string',
+            attributes: {
+              type: 'object',
+              properties: {
+                cardId: {
+                  type: 'string',
+                  const: 'http://localhost:4201/experiments/Friend/1',
+                },
+                patch: {
+                  type: 'object',
+                  properties: {
+                    attributes: {
+                      type: 'object',
+                      properties: {
+                        firstName: {
+                          type: 'string',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
             },
           },
-          required: ['card_id', 'attributes', 'description'],
+          required: ['attributes', 'description'],
         },
       },
     });
@@ -989,7 +1011,9 @@ module('getModifyPrompt', () => {
               openCardIds: ['http://localhost:4201/experiments/Friend/1'],
               tools: [
                 getPatchTool('http://localhost:4201/experiments/Friend/1', {
-                  firstName: { type: 'string' },
+                  attributes: {
+                    firstName: { type: 'string' },
+                  },
                 }),
               ],
               submode: 'interact',
@@ -1018,7 +1042,12 @@ module('getModifyPrompt', () => {
               openCardIds: ['http://localhost:4201/experiments/Meeting/2'],
               tools: [
                 getPatchTool('http://localhost:4201/experiments/Meeting/2', {
-                  location: { type: 'string' },
+                  attributes: {
+                    type: 'object',
+                    properties: {
+                      location: { type: 'string' },
+                    },
+                  },
                 }),
               ],
               submode: 'interact',
@@ -1048,18 +1077,33 @@ module('getModifyPrompt', () => {
           parameters: {
             type: 'object',
             properties: {
-              card_id: {
-                type: 'string',
-                const: 'http://localhost:4201/experiments/Meeting/2',
-              },
               description: {
                 type: 'string',
               },
-              location: {
-                type: 'string',
+              attributes: {
+                type: 'object',
+                properties: {
+                  cardId: {
+                    type: 'string',
+                    const: 'http://localhost:4201/experiments/Meeting/2',
+                  },
+                  patch: {
+                    type: 'object',
+                    properties: {
+                      attributes: {
+                        type: 'object',
+                        properties: {
+                          location: {
+                            type: 'string',
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
               },
             },
-            required: ['card_id', 'attributes', 'description'],
+            required: ['attributes', 'description'],
           },
         },
       });
@@ -1867,11 +1911,13 @@ module('getModifyPrompt', () => {
               id: 'tool-call-id-1',
               name: 'searchCard',
               arguments: {
-                description: "Search for card instances of type 'Author'",
-                filter: {
-                  type: {
-                    module: 'http://localhost:4201/drafts/author',
-                    name: 'Author',
+                attributes: {
+                  description: "Search for card instances of type 'Author'",
+                  filter: {
+                    type: {
+                      module: 'http://localhost:4201/drafts/author',
+                      name: 'Author',
+                    },
                   },
                 },
               },
diff --git a/packages/ai-bot/tests/responding-test.ts b/packages/ai-bot/tests/responding-test.ts
index 3ca3ff6ea5..5efcae9e4f 100644
--- a/packages/ai-bot/tests/responding-test.ts
+++ b/packages/ai-bot/tests/responding-test.ts
@@ -184,9 +184,15 @@ module('Responding', (hooks) => {
 
   test('Sends tool call event and replaces thinking message when tool call happens with no content', async () => {
     const patchArgs = {
-      card_id: 'card/1',
       description: 'A new thing',
-      attributes: { some: 'thing' },
+      attributes: {
+        cardId: 'card/1',
+        patch: {
+          attributes: {
+            some: 'thing',
+          },
+        },
+      },
     };
 
     await responder.initialize();
@@ -225,10 +231,14 @@ module('Responding', (hooks) => {
           id: 'some-tool-call-id',
           name: 'patchCard',
           arguments: {
-            card_id: 'card/1',
             description: 'A new thing',
             attributes: {
-              some: 'thing',
+              cardId: 'card/1',
+              patch: {
+                attributes: {
+                  some: 'thing',
+                },
+              },
             },
           },
         },
@@ -252,9 +262,15 @@ module('Responding', (hooks) => {
 
   test('Sends tool call event separately when content is sent before tool call', async () => {
     const patchArgs = {
-      card_id: 'card/1',
       description: 'A new thing',
-      attributes: { some: 'thing' },
+      attributes: {
+        cardId: 'card/1',
+        patch: {
+          attributes: {
+            some: 'thing',
+          },
+        },
+      },
     };
     await responder.initialize();
 
@@ -293,10 +309,14 @@ module('Responding', (hooks) => {
           id: 'some-tool-call-id',
           name: 'patchCard',
           arguments: {
-            card_id: 'card/1',
             description: 'A new thing',
             attributes: {
-              some: 'thing',
+              cardId: 'card/1',
+              patch: {
+                attributes: {
+                  some: 'thing',
+                },
+              },
             },
           },
         },
diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index ae13a75b27..362cdb5832 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -44,6 +44,7 @@ import {
   type Actions,
   type RealmInfo,
   CodeRef,
+  CommandContext,
 } from '@cardstack/runtime-common';
 import type { ComponentLike } from '@glint/template';
 import { initSharedState } from './shared-state';
@@ -130,6 +131,7 @@ interface NotLoadedValue {
 
 export interface CardContext {
   actions?: Actions;
+  commandContext?: CommandContext;
   cardComponentModifier?: typeof Modifier<{
     Args: {
       Named: {
diff --git a/packages/base/command-result.gts b/packages/base/command-result.gts
index 361bbfa950..4bb10ffbde 100644
--- a/packages/base/command-result.gts
+++ b/packages/base/command-result.gts
@@ -395,10 +395,14 @@ class CommandResultIsolated extends CommandResultEmbeddedView {
   @tracked showAllResults = true;
 
   get filterString() {
-    if (!this.args.model.toolCallArgs?.filter) {
+    if (!this.args.model.toolCallArgs?.attributes.filter) {
       return;
     }
-    return JSON.stringify(this.args.model.toolCallArgs.filter, null, 2);
+    return JSON.stringify(
+      this.args.model.toolCallArgs.attributes.filter,
+      null,
+      2,
+    );
   }
 }
 
diff --git a/packages/base/command.gts b/packages/base/command.gts
index 931daad66b..5c183af9c5 100644
--- a/packages/base/command.gts
+++ b/packages/base/command.gts
@@ -5,9 +5,11 @@ import {
   StringField,
   contains,
   field,
+  linksTo,
   primitive,
   queryableValue,
 } from './card-api';
+import CodeRefField from './code-ref';
 
 export type CommandStatus = 'applied' | 'ready';
 
@@ -49,3 +51,40 @@ export class CommandCard extends CardDef {
   @field eventId = contains(StringField);
   @field status = contains(CommandStatusField);
 }
+
+export class SaveCardInput extends CardDef {
+  @field realm = contains(StringField);
+  @field card = linksTo(CardDef);
+}
+
+class JsonField extends FieldDef {
+  static [primitive]: Record<string, any>;
+}
+
+export class PatchCardInput extends CardDef {
+  @field cardId = contains(StringField);
+  @field patch = contains(JsonField); //TODO: JSONField ?
+}
+
+export class ShowCardInput extends CardDef {
+  @field cardToShow = linksTo(CardDef);
+}
+
+export class SwitchSubmodeInput extends CardDef {
+  @field submode = contains(StringField);
+}
+
+export class CreateModuleInput extends CardDef {
+  @field code = contains(StringField);
+  @field realm = contains(StringField);
+  @field modulePath = contains(StringField);
+}
+
+export class ModuleCard extends CardDef {
+  @field module = contains(CodeRefField);
+}
+
+export class CreateInstanceInput extends CardDef {
+  @field module = contains(CodeRefField);
+  @field realm = contains(StringField);
+}
diff --git a/packages/base/field-component.gts b/packages/base/field-component.gts
index cad24e4d2a..ea8c4b24dd 100644
--- a/packages/base/field-component.gts
+++ b/packages/base/field-component.gts
@@ -49,6 +49,7 @@ const DEFAULT_CARD_CONTEXT = {
     modify() {}
   },
   actions: undefined,
+  commandContext: undefined,
 };
 
 export class CardContextConsumer extends Component<CardContextConsumerSignature> {
diff --git a/packages/base/matrix-event.gts b/packages/base/matrix-event.gts
index 65e5d5dfa0..41834d1352 100644
--- a/packages/base/matrix-event.gts
+++ b/packages/base/matrix-event.gts
@@ -2,7 +2,7 @@ import { LooseSingleCardDocument } from '@cardstack/runtime-common';
 import type { EventStatus, MatrixError } from 'matrix-js-sdk';
 import {
   FunctionToolCall,
-  type Schema,
+  type AttributesSchema,
 } from '@cardstack/runtime-common/helpers/ai';
 
 interface BaseMatrixEvent {
@@ -166,7 +166,7 @@ export interface Tool {
   function: {
     name: string;
     description: string;
-    parameters: Schema;
+    parameters: AttributesSchema;
   };
 }
 
@@ -196,7 +196,7 @@ export interface CardMessageContent {
     context: {
       openCardIds?: string[];
       tools: Tool[];
-      submode: string | undefined;
+      submode?: string;
     };
   };
 }
diff --git a/packages/boxel-ui/test-app/tests/integration/components/resizable-panel-group-test.gts b/packages/boxel-ui/test-app/tests/integration/components/resizable-panel-group-test.gts
index 18187bda59..feec0a96f6 100644
--- a/packages/boxel-ui/test-app/tests/integration/components/resizable-panel-group-test.gts
+++ b/packages/boxel-ui/test-app/tests/integration/components/resizable-panel-group-test.gts
@@ -121,7 +121,6 @@ orientationPropertiesToTest.forEach((orientationProperties) => {
               max-${orientationProperties.dimension}: 100%;
             }
         `;
-        console.log(renderController.panels[1]);
 
         await render(<template>
           {{! template-lint-disable no-inline-styles }}
diff --git a/packages/catalog-realm/AiAppGenerator/create-boxel-app-command.ts b/packages/catalog-realm/AiAppGenerator/create-boxel-app-command.ts
new file mode 100644
index 0000000000..b0ff17480e
--- /dev/null
+++ b/packages/catalog-realm/AiAppGenerator/create-boxel-app-command.ts
@@ -0,0 +1,73 @@
+import { CardDef } from 'https://cardstack.com/base/card-api';
+import {
+  CreateInstanceInput,
+  ShowCardInput,
+} from 'https://cardstack.com/base/command';
+import { Command } from '@cardstack/runtime-common';
+import CreateProductRequirementsInstance, {
+  CreateProductRequirementsInput,
+} from './create-product-requirements-command';
+import GenerateCodeFromPRDCommand, {
+  GenerateCodeFromPRDInput,
+} from './generate-code-from-prd-command';
+
+export { CreateProductRequirementsInput };
+
+export default class CreateBoxelApp extends Command<
+  CreateProductRequirementsInput,
+  CardDef
+> {
+  inputType = CreateProductRequirementsInput;
+
+  protected async run(input: CreateProductRequirementsInput): Promise<CardDef> {
+    // Create PRD
+    let createPRDCommand = new CreateProductRequirementsInstance(
+      this.commandContext,
+      undefined,
+    );
+    let { productRequirements: prdCard, roomId } =
+      await createPRDCommand.execute(input);
+    let showCardCommand = this.commandContext.lookupCommand<
+      ShowCardInput,
+      undefined
+    >('show-card');
+    let showPRDCardInput = new ShowCardInput();
+    showPRDCardInput.cardToShow = prdCard;
+    await showCardCommand.execute(showPRDCardInput);
+    // Generate App
+    let generateAppCommand = new GenerateCodeFromPRDCommand(
+      this.commandContext,
+      undefined,
+    );
+    let generateAppInput = new GenerateCodeFromPRDInput();
+    generateAppInput.productRequirements = prdCard;
+    generateAppInput.realm = input.realm;
+    generateAppInput.roomId = roomId;
+    let { module: moduleCard } = await generateAppCommand.execute(
+      generateAppInput,
+    );
+    // Create instance
+    let createInstanceCommand = this.commandContext.lookupCommand<
+      CreateInstanceInput,
+      CardDef
+    >('createInstance');
+    let createInstanceInput = new CreateInstanceInput();
+    createInstanceInput.module = moduleCard;
+    createInstanceInput.realm = input.realm;
+    let appCard = await createInstanceCommand.execute(createInstanceInput);
+    // open new app card
+    let showCardInput = new ShowCardInput();
+    showCardInput.cardToShow = appCard;
+    await showCardCommand.execute(showCardInput);
+    //   // generate some sample data
+    //   // Notes:
+    //   //  - We're going to need to look through the module and get the types?
+    return appCard;
+  }
+
+  async getInputType(): Promise<
+    new (args: any) => CreateProductRequirementsInput
+  > {
+    return CreateProductRequirementsInput;
+  }
+}
diff --git a/packages/catalog-realm/AiAppGenerator/create-product-requirements-command.ts b/packages/catalog-realm/AiAppGenerator/create-product-requirements-command.ts
new file mode 100644
index 0000000000..1f9ea3bd23
--- /dev/null
+++ b/packages/catalog-realm/AiAppGenerator/create-product-requirements-command.ts
@@ -0,0 +1,122 @@
+import { Command } from '@cardstack/runtime-common';
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  linksTo,
+} from 'https://cardstack.com/base/card-api';
+import { ProductRequirementDocument } from '../product-requirement-document';
+import { SkillCard } from 'https://cardstack.com/base/skill-card';
+import {
+  PatchCardInput,
+  SaveCardInput,
+} from 'https://cardstack.com/base/command';
+
+export class CreateProductRequirementsInput extends CardDef {
+  @field targetAudience = contains(StringField);
+  @field productDescription = contains(StringField);
+  @field features = contains(StringField);
+  @field realm = contains(StringField);
+}
+
+class CreateProductRequirementsResult extends CardDef {
+  @field productRequirements = linksTo(ProductRequirementDocument);
+  @field roomId = contains(StringField);
+}
+
+export default class CreateProductRequirementsInstance extends Command<
+  CreateProductRequirementsInput,
+  CreateProductRequirementsResult
+> {
+  inputType = CreateProductRequirementsInput;
+
+  get skillCard() {
+    return new SkillCard({
+      id: 'SkillCard1',
+      name: 'PRD Helper',
+      description:
+        'This skill card can be used to help with creating product requirements',
+      instructions:
+        'You are a helpful assistant that can help with creating product requirements, etc. You *MUST* make the patchCard function call',
+    });
+  }
+
+  createPrompt(input: CreateProductRequirementsInput) {
+    return `Create product requirements for ${input.targetAudience} with the following description: ${input.productDescription}. Focus on the following features: ${input.features}`;
+  }
+
+  protected async run(
+    input: CreateProductRequirementsInput,
+  ): Promise<CreateProductRequirementsResult> {
+    console.log('Input into the run', input);
+    // Create new card
+    let prdCard = new ProductRequirementDocument();
+    console.log('prdCard', prdCard);
+
+    let saveCardCommand = this.commandContext.lookupCommand<
+      SaveCardInput,
+      undefined
+    >('save-card'); // lookupCommand creates the instance and passes in the context
+    console.log('saveCardCommand', saveCardCommand);
+    let SaveCardInputType = await saveCardCommand.getInputType();
+    await saveCardCommand.execute(
+      new SaveCardInputType({
+        realm: input.realm,
+        card: prdCard,
+      }),
+    );
+    console.log('prdCard after save', prdCard);
+
+    // Get patch command, this takes the card and returns a command that can be used to patch the card
+    let patchPRDCommand = this.commandContext.lookupCommand<
+      PatchCardInput,
+      undefined,
+      { cardType: typeof ProductRequirementDocument }
+    >('patch-card', { cardType: ProductRequirementDocument });
+    console.log('patchPRDCommand', patchPRDCommand);
+
+    // This should return a session ID so that we can potentially send followup messages
+    // This should delegate to a matrix service method. Besides actually sending the message,
+    // with attached cards, skill cards, and commands, it should also be responsible for assigning
+    // ids to the commands which are used to give the tools unique names (e.g. patchCard_ABC)
+    // service should maintain a mapping of commandIds to command instances in order to map an apply
+    // back to the correct command instance
+    // Auto execute commands are commands that should be executed automatically if they are returned
+    // as tool calls from the AI.
+
+    let { roomId } = await this.commandContext.sendAiAssistantMessage({
+      show: false, // maybe? open the side panel
+      prompt: this.createPrompt(input),
+      attachedCards: [prdCard],
+      skillCards: [this.skillCard],
+      commands: [{ command: patchPRDCommand, autoExecute: true }], // this should persist over multiple messages, matrix service is responsible to tracking whic
+    });
+
+    console.log('roomId', roomId);
+
+    // Wait for the PRD command to have been applied
+    await patchPRDCommand.waitForNextCompletion();
+    // TODO: alternate approach is to have room have a goal, and monitor for that completion as opposed to command completion
+    // TODO: alternate simpler approach, send a message and wait for a reply. If the reply is a the tool call, continue, otherwise, show room to the user and wait for the next reply
+
+    console.log('prdCard after patch', prdCard);
+
+    let reloadCommand = await this.commandContext.lookupCommand<
+      CardDef,
+      undefined
+    >('reload-card');
+    await reloadCommand.execute(prdCard);
+    console.log('prdCard after reload', prdCard);
+    let result = new CreateProductRequirementsResult();
+    result.productRequirements = prdCard;
+    result.roomId = roomId;
+    return result;
+  }
+
+  async getInputType(): Promise<
+    new (args: any) => CreateProductRequirementsInput
+  > {
+    return CreateProductRequirementsInput;
+  }
+}
diff --git a/packages/catalog-realm/AiAppGenerator/generate-code-from-prd-command.ts b/packages/catalog-realm/AiAppGenerator/generate-code-from-prd-command.ts
new file mode 100644
index 0000000000..388793e229
--- /dev/null
+++ b/packages/catalog-realm/AiAppGenerator/generate-code-from-prd-command.ts
@@ -0,0 +1,78 @@
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  linksTo,
+} from 'https://cardstack.com/base/card-api';
+import { ProductRequirementDocument } from '../product-requirement-document';
+import CodeRefField from '../../base/code-ref';
+import { Command } from '@cardstack/runtime-common';
+import { SkillCard } from 'https://cardstack.com/base/skill-card';
+
+export class GenerateCodeFromPRDInput extends CardDef {
+  @field productRequirements = linksTo(ProductRequirementDocument);
+  @field realm = contains(StringField);
+  @field roomId = contains(StringField);
+}
+import {
+  CreateModuleInput,
+  ModuleCard,
+} from 'https://cardstack.com/base/command';
+
+class GenerateCodeFromPRDResult extends CardDef {
+  @field module = contains(CodeRefField);
+  @field roomId = contains(StringField);
+}
+
+export default class GenerateCodeFromPRDCommand extends Command<
+  GenerateCodeFromPRDInput,
+  GenerateCodeFromPRDResult
+> {
+  get skillCard() {
+    return new SkillCard({
+      name: 'Boxel App Generator',
+      description:
+        'This skill card helps generate code from product requirements',
+      instructions:
+        'You are an expert programmer. Given product requirements, generate appropriate code that implements those requirements. Use the createModule command to create the module with the generated code.',
+    });
+  }
+
+  async getInputType(): Promise<new (args: any) => GenerateCodeFromPRDInput> {
+    return GenerateCodeFromPRDInput;
+  }
+
+  createPrompt(_prdCard: ProductRequirementDocument) {
+    // TODO: use this PRD card value?
+    return `Please analyze the provided product requirements and generate appropriate code to implement them. Consider best practices, maintainability, and performance.`;
+  }
+
+  protected async run(
+    input: GenerateCodeFromPRDInput,
+  ): Promise<GenerateCodeFromPRDResult> {
+    // Get the create module command
+    let createModuleCommand = this.commandContext.lookupCommand<
+      CreateModuleInput,
+      ModuleCard
+    >('createModule');
+
+    // Send message to AI assistant with the PRD card and wait for it to generate code
+    let { roomId } = await this.commandContext.sendAiAssistantMessage({
+      roomId: input.roomId,
+      show: true,
+      prompt: this.createPrompt(input.productRequirements),
+      attachedCards: [input.productRequirements],
+      skillCards: [this.skillCard],
+      commands: [{ command: createModuleCommand, autoExecute: true }],
+    });
+
+    // Wait for the module to be created
+    const moduleCard = await createModuleCommand.waitForNextCompletion();
+
+    let result = new GenerateCodeFromPRDResult();
+    result.module = moduleCard.module;
+    result.roomId = roomId;
+    return result;
+  }
+}
diff --git a/packages/catalog-realm/ai-app-generator.gts b/packages/catalog-realm/ai-app-generator.gts
index 70d8b4821d..f85aaf8af6 100644
--- a/packages/catalog-realm/ai-app-generator.gts
+++ b/packages/catalog-realm/ai-app-generator.gts
@@ -25,6 +25,9 @@ import {
 } from '@cardstack/runtime-common';
 import { AppCard, AppCardTemplate, CardsGrid } from './app-card';
 import CPU from '@cardstack/boxel-icons/cpu';
+import CreateBoxelApp, {
+  CreateProductRequirementsInput,
+} from './AiAppGenerator/create-boxel-app-command';
 
 const getCardTypeQuery = (cardRef: CodeRef, excludedId?: string): Query => {
   let filter: Query['filter'];
@@ -297,7 +300,7 @@ class DashboardTab extends GlimmerComponent<{
           @prompt={{this.prompt}}
           @setPrompt={{this.setPrompt}}
           @generateProductRequirementsDoc={{this.generateProductRequirementsDoc}}
-          @isLoading={{this.generateRequirements.isRunning}}
+          @isLoading={{this.isGenerating}}
         />
         {{#if this.errorMessage}}
           <p class='error'>{{this.errorMessage}}</p>
@@ -347,66 +350,32 @@ class DashboardTab extends GlimmerComponent<{
   };
   @tracked errorMessage = '';
   @tracked prompt: Prompt = this.promptReset;
+  @tracked isGenerating = false;
 
   @action setPrompt(key: string, value: string) {
     this.prompt = { ...this.prompt, [key]: value };
   }
 
-  @action generateProductRequirementsDoc() {
-    let appTitle = `${this.prompt.domain} ${this.prompt.appType}`;
-    let requirements = this.prompt.customRequirements
-      ? `that has these features: ${this.prompt.customRequirements}`
-      : '';
-    let prompt = `I want to make a ${this.prompt.appType} tailored for a ${this.prompt.domain} ${requirements}`;
-    this.generateRequirements.perform(this.prdCardRef, {
-      data: {
-        attributes: { appTitle, prompt },
-        meta: {
-          adoptsFrom: this.prdCardRef,
-          realmURL: this.args.currentRealm?.href,
-        },
-      },
-    });
-  }
-  private generateRequirements = restartableTask(
-    async (ref: CodeRef, doc: LooseSingleCardDocument) => {
-      try {
-        this.errorMessage = '';
-        let { createCard, viewCard, runCommand } =
-          this.args.context?.actions ?? {};
-        if (!createCard || !viewCard || !runCommand) {
-          throw new Error('Missing required card actions');
-        }
-
-        let card = await createCard(ref, this.args.currentRealm, {
-          doc,
-          cardModeAfterCreation: 'isolated',
-        });
-        if (!card) {
-          throw new Error('Error: Failed to create card');
-        }
-
-        // Construct the relative URL for the SkillCard
-        let skillCardUrl = new URL(
-          './SkillCard/generate-product-requirements',
-          import.meta.url,
-        ).href;
-
-        // Update the runCommand call to use the constructed URL
-        await runCommand(
-          card,
-          skillCardUrl,
-          'Generate product requirements document',
-        );
-        this.prompt = this.promptReset;
-        this.args.setActiveTab?.('requirements');
-      } catch (e) {
-        this.errorMessage =
-          e instanceof Error ? `${e.name}: ${e.message}` : 'An error occurred.';
-        throw e;
-      }
-    },
-  );
+  generateProductRequirementsDoc = async () => {
+    let commandContext = this.args.context?.commandContext;
+    if (!commandContext) {
+      throw new Error('Missing commandContext');
+    }
+    let command = new CreateBoxelApp(commandContext, undefined);
+    this.isGenerating = true;
+    try {
+      await command.execute(
+        new CreateProductRequirementsInput({
+          productDescription: this.prompt.appType,
+          targetAudience: this.prompt.domain,
+          features: this.prompt.customRequirements,
+          realm: this.args.currentRealm,
+        }),
+      );
+    } finally {
+      this.isGenerating = false;
+    }
+  };
 }
 
 class RequirementsTab extends GlimmerComponent<{
diff --git a/packages/catalog-realm/product-requirement-document.gts b/packages/catalog-realm/product-requirement-document.gts
index 0a787a0c29..27c3415c78 100644
--- a/packages/catalog-realm/product-requirement-document.gts
+++ b/packages/catalog-realm/product-requirement-document.gts
@@ -13,8 +13,7 @@ import {
 import { Button } from '@cardstack/boxel-ui/components';
 import { ImagePlaceholder } from '@cardstack/boxel-ui/icons';
 import { bool, cn, not } from '@cardstack/boxel-ui/helpers';
-import { on } from '@ember/modifier';
-import { action } from '@ember/object';
+import { on } from '@ember/modifier'; // TODO: why is this a type error???
 import { tracked } from '@glimmer/tracking';
 import { restartableTask } from 'ember-concurrency';
 import { AppCard } from './app-card';
@@ -248,12 +247,12 @@ class Isolated extends Component<typeof ProductRequirementDocument> {
     return this.args.model[realmURL];
   }
 
-  @action generateApp() {
+  generateApp = () => {
     this._generateCode.perform();
-  }
-  @action createInstance() {
+  };
+  createInstance = () => {
     this._createInstance.perform();
-  }
+  };
 
   private _generateCode = restartableTask(async () => {
     this.errorMessage = '';
@@ -317,7 +316,10 @@ class Isolated extends Component<typeof ProductRequirementDocument> {
                 title: this.args.model.appTitle,
                 moduleId: moduleURL,
               },
-              meta: { adoptsFrom: moduleRef, realmURL: this.currentRealm },
+              meta: {
+                adoptsFrom: moduleRef,
+                realmURL: this.currentRealm.href,
+              },
             },
           },
           cardModeAfterCreation: 'isolated',
@@ -336,7 +338,7 @@ class Isolated extends Component<typeof ProductRequirementDocument> {
     }
   });
 
-  @action viewModule() {
+  viewModule = () => {
     this.errorMessage = '';
     if (!this.args.model.moduleURL) {
       this.errorMessage = 'Module url is not available';
@@ -351,12 +353,12 @@ class Isolated extends Component<typeof ProductRequirementDocument> {
       new URL(this.args.model.moduleURL),
       'code',
     );
-  }
+  };
 
-  @action reset() {
+  reset = () => {
     this.args.model.moduleURL = undefined;
     this.args.model.appInstances = undefined;
-  }
+  };
 }
 
 export class ProductRequirementDocument extends CardDef {
diff --git a/packages/catalog-realm/types/index.d.ts b/packages/catalog-realm/types/index.d.ts
new file mode 100644
index 0000000000..2109bac67a
--- /dev/null
+++ b/packages/catalog-realm/types/index.d.ts
@@ -0,0 +1,2 @@
+import 'ember-source/types';
+import 'ember-source/types/preview';
diff --git a/packages/experiments-realm/ProductRequirementDocument/4165a295-e5ed-4922-a271-3fe49c79b482.json b/packages/experiments-realm/ProductRequirementDocument/4165a295-e5ed-4922-a271-3fe49c79b482.json
index 77cbc1c5fa..86f5e8e2cc 100644
--- a/packages/experiments-realm/ProductRequirementDocument/4165a295-e5ed-4922-a271-3fe49c79b482.json
+++ b/packages/experiments-realm/ProductRequirementDocument/4165a295-e5ed-4922-a271-3fe49c79b482.json
@@ -27,9 +27,9 @@
     },
     "meta": {
       "adoptsFrom": {
-        "module": "../product-requirement-document",
+        "module": "/catalog/product-requirement-document",
         "name": "ProductRequirementDocument"
       }
     }
   }
-}
\ No newline at end of file
+}
diff --git a/packages/experiments-realm/ProductRequirementDocument/6724b1e4-e620-4e62-86c4-4cab1c132170.json b/packages/experiments-realm/ProductRequirementDocument/6724b1e4-e620-4e62-86c4-4cab1c132170.json
index f03dd076f1..a5e6999396 100644
--- a/packages/experiments-realm/ProductRequirementDocument/6724b1e4-e620-4e62-86c4-4cab1c132170.json
+++ b/packages/experiments-realm/ProductRequirementDocument/6724b1e4-e620-4e62-86c4-4cab1c132170.json
@@ -20,7 +20,7 @@
     },
     "meta": {
       "adoptsFrom": {
-        "module": "../product-requirement-document",
+        "module": "/catalog/product-requirement-document",
         "name": "ProductRequirementDocument"
       }
     }
diff --git a/packages/experiments-realm/ProductRequirementDocument/8a2268d9-89f9-4d4c-ab56-dfb4471814a4.json b/packages/experiments-realm/ProductRequirementDocument/8a2268d9-89f9-4d4c-ab56-dfb4471814a4.json
index 027866a03b..8de49344f4 100644
--- a/packages/experiments-realm/ProductRequirementDocument/8a2268d9-89f9-4d4c-ab56-dfb4471814a4.json
+++ b/packages/experiments-realm/ProductRequirementDocument/8a2268d9-89f9-4d4c-ab56-dfb4471814a4.json
@@ -20,7 +20,7 @@
     },
     "meta": {
       "adoptsFrom": {
-        "module": "../product-requirement-document",
+        "module": "/catalog/product-requirement-document",
         "name": "ProductRequirementDocument"
       }
     }
diff --git a/packages/host/app/commands/create-module.ts b/packages/host/app/commands/create-module.ts
new file mode 100644
index 0000000000..819eb633d7
--- /dev/null
+++ b/packages/host/app/commands/create-module.ts
@@ -0,0 +1,43 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import type CardService from '../services/card-service';
+
+import type LoaderService from '../services/loader-service';
+
+export default class CreateModuleCommand extends Command<
+  BaseCommandModule.CreateModuleInput,
+  undefined,
+  { cardType: typeof CardDef }
+> {
+  @service private declare cardService: CardService;
+  @service private declare loaderService: LoaderService;
+
+  description = `Create a new module, errors if there is an existing module with the same name.`;
+
+  async getInputType() {
+    let commandModule = await this.loaderService.loader.import<
+      typeof BaseCommandModule
+    >(`${baseRealm.url}command`);
+    const { CreateModuleInput } = commandModule;
+    // Can we define one on the fly?
+    return CreateModuleInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.CreateModuleInput,
+  ): Promise<undefined> {
+    // TODO: check if currently exists using authedFetch
+    await this.cardService.saveSource(
+      new URL(input.modulePath, input.realm),
+      input.code,
+    );
+    // We have no return here, we need to return a reference to the module created
+    // and potentially also identify exported cards from it
+    // We should also return error messages if any
+  }
+}
diff --git a/packages/host/app/commands/patch-card.ts b/packages/host/app/commands/patch-card.ts
new file mode 100644
index 0000000000..3488d5def9
--- /dev/null
+++ b/packages/host/app/commands/patch-card.ts
@@ -0,0 +1,85 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import {
+  type AttributesSchema,
+  type CardSchema,
+  type ObjectSchema,
+  type RelationshipsSchema,
+  generateJsonSchemaForCardType,
+} from '@cardstack/runtime-common/helpers/ai';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import OperatorModeStateService from '../services/operator-mode-state-service';
+
+import type LoaderService from '../services/loader-service';
+
+export default class PatchCardCommand extends Command<
+  BaseCommandModule.PatchCardInput,
+  undefined,
+  { cardType: typeof CardDef }
+> {
+  @service private declare operatorModeStateService: OperatorModeStateService;
+  @service private declare loaderService: LoaderService;
+
+  description = `Propose a patch to an existing card to change its contents. Any attributes specified will be fully replaced, return the minimum required to make the change. If a relationship field value is removed, set the self property of the specific item to null. When editing a relationship array, display the full array in the patch code. Ensure the description explains what change you are making. Do NOT leave out the cardId or patch fields or this tool will not work.`;
+
+  async getInputType() {
+    let commandModule = await this.loaderService.loader.import<
+      typeof BaseCommandModule
+    >(`${baseRealm.url}command`);
+    const { PatchCardInput } = commandModule;
+    // Can we define one on the fly?
+    return PatchCardInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.PatchCardInput,
+  ): Promise<undefined> {
+    if (!input.cardId || !input.patch) {
+      throw new Error(
+        "Patch command can't run because it doesn't have all the fields in arguments returned by open ai",
+      );
+    }
+    await this.operatorModeStateService.patchCard.perform(input.cardId, {
+      attributes: input.patch.attributes,
+      relationships: input.patch.relationships,
+    });
+  }
+
+  async getInputJsonSchema(
+    cardApi: typeof CardAPI,
+    mappings: Map<typeof CardAPI.FieldDef, AttributesSchema>,
+  ): Promise<CardSchema> {
+    let cardTypeToPatch = this.configuration.cardType;
+    let cardTypeToPatchSchema = generateJsonSchemaForCardType(
+      cardTypeToPatch,
+      cardApi,
+      mappings,
+    );
+    const inputTypeCardSchema = {
+      attributes: {
+        type: 'object',
+        properties: {
+          cardId: { type: 'string' },
+          patch: {
+            type: 'object',
+            properties: {
+              attributes: cardTypeToPatchSchema.attributes,
+              relationships: cardTypeToPatchSchema.relationships,
+            },
+          } as ObjectSchema,
+        },
+      } as AttributesSchema,
+      relationships: {
+        type: 'object',
+        properties: {},
+      } as RelationshipsSchema,
+    };
+    return inputTypeCardSchema;
+  }
+}
diff --git a/packages/host/app/commands/reload-card.ts b/packages/host/app/commands/reload-card.ts
new file mode 100644
index 0000000000..218e2d94ff
--- /dev/null
+++ b/packages/host/app/commands/reload-card.ts
@@ -0,0 +1,28 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+
+import type * as CardAPIModule from 'https://cardstack.com/base/card-api';
+
+import type CardService from '../services/card-service';
+import type LoaderService from '../services/loader-service';
+
+export default class ReloadCardCommand extends Command<CardDef, undefined> {
+  @service private declare cardService: CardService;
+  @service private declare loaderService: LoaderService;
+
+  async getInputType() {
+    let cardApiModule = await this.loaderService.loader.import<
+      typeof CardAPIModule
+    >(`${baseRealm.url}card-api`);
+    const { CardDef } = cardApiModule;
+    return CardDef;
+  }
+
+  protected async run(input: CardDef): Promise<undefined> {
+    // TODO: handle case where card is already saved and a different input.realm is provided
+    await this.cardService.reloadCard(input);
+  }
+}
diff --git a/packages/host/app/commands/save-card.ts b/packages/host/app/commands/save-card.ts
new file mode 100644
index 0000000000..612067b83c
--- /dev/null
+++ b/packages/host/app/commands/save-card.ts
@@ -0,0 +1,31 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import type CardService from '../services/card-service';
+import type LoaderService from '../services/loader-service';
+
+export default class SaveCardCommand extends Command<
+  BaseCommandModule.SaveCardInput,
+  undefined
+> {
+  @service private declare cardService: CardService;
+  @service private declare loaderService: LoaderService;
+
+  async getInputType() {
+    let commandModule = await this.loaderService.loader.import<
+      typeof BaseCommandModule
+    >(`${baseRealm.url}command`);
+    const { SaveCardInput } = commandModule;
+    return SaveCardInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.SaveCardInput,
+  ): Promise<undefined> {
+    // TODO: handle case where card is already saved and a different input.realm is provided
+    await this.cardService.saveModel(this, input.card, input.realm);
+  }
+}
diff --git a/packages/host/app/commands/show-card.ts b/packages/host/app/commands/show-card.ts
new file mode 100644
index 0000000000..81f40d3aa1
--- /dev/null
+++ b/packages/host/app/commands/show-card.ts
@@ -0,0 +1,44 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import type LoaderService from '../services/loader-service';
+import type OperatorModeStateService from '../services/operator-mode-state-service';
+
+export default class ShowCardCommand extends Command<
+  BaseCommandModule.ShowCardInput,
+  undefined
+> {
+  @service private declare operatorModeStateService: OperatorModeStateService;
+  @service private declare loaderService: LoaderService;
+
+  description = 'Show a card in the UI';
+
+  async getInputType() {
+    let commandModule = await this.loaderService.loader.import<
+      typeof BaseCommandModule
+    >(`${baseRealm.url}command`);
+    const { ShowCardInput } = commandModule;
+    return ShowCardInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.ShowCardInput,
+  ): Promise<undefined> {
+    if (this.operatorModeStateService.state?.submode != 'interact') {
+      // switch to interact mode
+      this.operatorModeStateService.updateSubmode('interact');
+    }
+    let newStackIndex = Math.min(
+      this.operatorModeStateService.numberOfStacks(),
+      1,
+    );
+    let newStackItem = await this.operatorModeStateService.createStackItem(
+      input.cardToShow,
+      newStackIndex,
+    );
+    this.operatorModeStateService.addItemToStack(newStackItem);
+  }
+}
diff --git a/packages/host/app/commands/switch-submode.ts b/packages/host/app/commands/switch-submode.ts
new file mode 100644
index 0000000000..eb6b730a09
--- /dev/null
+++ b/packages/host/app/commands/switch-submode.ts
@@ -0,0 +1,63 @@
+import { service } from '@ember/service';
+
+import { Command, baseRealm } from '@cardstack/runtime-common';
+
+import { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import { Submodes } from '../components/submode-switcher';
+
+import type LoaderService from '../services/loader-service';
+import type OperatorModeStateService from '../services/operator-mode-state-service';
+
+export default class SwitchSubmodeCommand extends Command<
+  BaseCommandModule.SwitchSubmodeInput,
+  undefined
+> {
+  @service private declare operatorModeStateService: OperatorModeStateService;
+  @service private declare loaderService: LoaderService;
+
+  description =
+    'Navigate the UI to another submode. Possible values for submode are "interact" and "code".';
+
+  async getInputType() {
+    let commandModule = await this.loaderService.loader.import<
+      typeof BaseCommandModule
+    >(`${baseRealm.url}command`);
+    const { SwitchSubmodeInput } = commandModule;
+    return SwitchSubmodeInput;
+  }
+
+  private get allStackItems() {
+    return this.operatorModeStateService.state?.stacks.flat() ?? [];
+  }
+
+  private get lastCardInRightMostStack(): CardDef | null {
+    if (this.allStackItems.length <= 0) {
+      return null;
+    }
+
+    return this.allStackItems[this.allStackItems.length - 1].card;
+  }
+
+  protected async run(
+    input: BaseCommandModule.SwitchSubmodeInput,
+  ): Promise<undefined> {
+    switch (input.submode) {
+      case Submodes.Interact:
+        this.operatorModeStateService.updateCodePath(null);
+        break;
+      case Submodes.Code:
+        this.operatorModeStateService.updateCodePath(
+          this.lastCardInRightMostStack
+            ? new URL(this.lastCardInRightMostStack.id + '.json')
+            : null,
+        );
+        break;
+      default:
+        throw new Error(`invalid submode specified: ${input.submode}`);
+    }
+
+    this.operatorModeStateService.updateSubmode(input.submode);
+  }
+}
diff --git a/packages/host/app/components/matrix/room-message.gts b/packages/host/app/components/matrix/room-message.gts
index 02054230fd..164bdd2e2b 100644
--- a/packages/host/app/components/matrix/room-message.gts
+++ b/packages/host/app/components/matrix/room-message.gts
@@ -312,15 +312,12 @@ export default class RoomMessage extends Component<Signature> {
     if (this.failedCommandState) {
       return `Failed to apply changes. ${this.failedCommandState.message}`;
     }
-
     if (this.args.message.errorMessage) {
       return this.args.message.errorMessage;
     }
-
     if (this.streamingTimeout) {
       return 'This message was processing for too long. Please try again.';
     }
-
     if (!this.resources?.errors) {
       return undefined;
     }
diff --git a/packages/host/app/components/matrix/room.gts b/packages/host/app/components/matrix/room.gts
index 4645275f31..ed55b6f833 100644
--- a/packages/host/app/components/matrix/room.gts
+++ b/packages/host/app/components/matrix/room.gts
@@ -570,14 +570,18 @@ export default class Room extends Component<Signature> {
       let activeSkillCards = this.skills
         .filter((skill) => skill.isActive)
         .map((c) => c.card);
-      await this.matrixService.sendMessage(
-        this.args.roomId,
-        message,
-        cards,
-        activeSkillCards,
-        clientGeneratedId,
-        context,
-      );
+      try {
+        await this.matrixService.sendMessage(
+          this.args.roomId,
+          message,
+          cards,
+          activeSkillCards,
+          clientGeneratedId,
+          context,
+        );
+      } catch (e) {
+        console.error('Error sending message', e);
+      }
     },
   );
 
diff --git a/packages/host/app/components/operator-mode/interact-submode.gts b/packages/host/app/components/operator-mode/interact-submode.gts
index e8fed407d0..b833617603 100644
--- a/packages/host/app/components/operator-mode/interact-submode.gts
+++ b/packages/host/app/components/operator-mode/interact-submode.gts
@@ -40,7 +40,11 @@ import { stackBackgroundsResource } from '@cardstack/host/resources/stack-backgr
 
 import type MatrixService from '@cardstack/host/services/matrix-service';
 
-import { type CardDef, type Format } from 'https://cardstack.com/base/card-api';
+import type {
+  CardContext,
+  CardDef,
+  Format,
+} from 'https://cardstack.com/base/card-api';
 
 import CopyButton from './copy-button';
 import DeleteModal from './delete-modal';
@@ -51,6 +55,7 @@ import SubmodeLayout from './submode-layout';
 import type { StackItemComponentAPI } from './stack-item';
 
 import type CardService from '../../services/card-service';
+import type CommandService from '../../services/command-service';
 import type OperatorModeStateService from '../../services/operator-mode-state-service';
 import type Realm from '../../services/realm';
 
@@ -140,6 +145,7 @@ interface Signature {
 
 export default class InteractSubmode extends Component<Signature> {
   @service private declare cardService: CardService;
+  @service private declare commandService: CommandService;
   @service private declare matrixService: MatrixService;
   @service private declare operatorModeStateService: OperatorModeStateService;
   @service private declare realm: Realm;
@@ -657,9 +663,14 @@ export default class InteractSubmode extends Component<Signature> {
 
   @provide(CardContextName)
   // @ts-ignore "cardContext is declared but not used"
-  private get cardContext() {
+  private get cardContext(): Omit<
+    CardContext,
+    'prerenderedCardSearchComponent'
+  > {
     return {
       actions: this.publicAPI(this, 0),
+      // TODO: should we include this here??
+      commandContext: this.commandService.commandContext,
     };
   }
 
@@ -719,6 +730,7 @@ export default class InteractSubmode extends Component<Signature> {
                 @stackItems={{stack}}
                 @stackIndex={{stackIndex}}
                 @publicAPI={{this.publicAPI this stackIndex}}
+                @commandContext={{this.commandService.commandContext}}
                 @close={{perform this.close}}
                 @onSelectedCards={{this.onSelectedCards}}
                 @setupStackItem={{this.setupStackItem}}
diff --git a/packages/host/app/components/operator-mode/stack-item.gts b/packages/host/app/components/operator-mode/stack-item.gts
index 7c3b58259d..de579fcce8 100644
--- a/packages/host/app/components/operator-mode/stack-item.gts
+++ b/packages/host/app/components/operator-mode/stack-item.gts
@@ -45,6 +45,7 @@ import {
   RealmURLContextName,
   Deferred,
   cardTypeIcon,
+  CommandContext,
 } from '@cardstack/runtime-common';
 
 import config from '@cardstack/host/config/environment';
@@ -52,6 +53,7 @@ import config from '@cardstack/host/config/environment';
 import { type StackItem, isIndexCard } from '@cardstack/host/lib/stack-item';
 
 import type {
+  CardContext,
   CardDef,
   Format,
   FieldType,
@@ -82,6 +84,7 @@ interface Signature {
     stackItems: StackItem[];
     index: number;
     publicAPI: Actions;
+    commandContext: CommandContext;
     close: (item: StackItem) => void;
     dismissStackedCardsAbove: (stackIndex: number) => void;
     onSelectedCards: (
@@ -232,10 +235,14 @@ export default class OperatorModeStackItem extends Component<Signature> {
     return !this.isBuried;
   }
 
-  private get cardContext() {
+  private get cardContext(): Omit<
+    CardContext,
+    'prerenderedCardSearchComponent'
+  > {
     return {
       cardComponentModifier: this.cardTracker.trackElement,
       actions: this.args.publicAPI,
+      commandContext: this.args.commandContext,
     };
   }
 
diff --git a/packages/host/app/components/operator-mode/stack.gts b/packages/host/app/components/operator-mode/stack.gts
index 49242049e4..6e487ab86c 100644
--- a/packages/host/app/components/operator-mode/stack.gts
+++ b/packages/host/app/components/operator-mode/stack.gts
@@ -3,7 +3,7 @@ import Component from '@glimmer/component';
 import { task } from 'ember-concurrency';
 import perform from 'ember-concurrency/helpers/perform';
 
-import type { Actions } from '@cardstack/runtime-common';
+import type { Actions, CommandContext } from '@cardstack/runtime-common';
 
 import type { StackItem } from '@cardstack/host/lib/stack-item';
 
@@ -21,6 +21,7 @@ interface Signature {
     stackItems: StackItem[];
     stackIndex: number;
     publicAPI: Actions;
+    commandContext: CommandContext;
     close: (stackItem: StackItem) => void;
     onSelectedCards: (
       selectedCards: CardDefOrId[],
@@ -85,6 +86,7 @@ export default class OperatorModeStack extends Component<Signature> {
             @index={{i}}
             @stackItems={{@stackItems}}
             @publicAPI={{@publicAPI}}
+            @commandContext={{@commandContext}}
             @dismissStackedCardsAbove={{perform this.dismissStackedCardsAbove}}
             @close={{@close}}
             @onSelectedCards={{@onSelectedCards}}
diff --git a/packages/host/app/components/submode-switcher.gts b/packages/host/app/components/submode-switcher.gts
index 3fd24e0eeb..5aae5885c3 100644
--- a/packages/host/app/components/submode-switcher.gts
+++ b/packages/host/app/components/submode-switcher.gts
@@ -36,7 +36,7 @@ interface Signature {
 
 export default class SubmodeSwitcher extends Component<Signature> {
   <template>
-    <div data-test-submode-switcher ...attributes>
+    <div data-test-submode-switcher={{@submode}} ...attributes>
       <BoxelDropdown @contentClass='submode-switcher-dropdown'>
         <:trigger as |bindings|>
           <Button
diff --git a/packages/host/app/resources/card-resource.ts b/packages/host/app/resources/card-resource.ts
index 7fd7da2d65..a5e3b2ee70 100644
--- a/packages/host/app/resources/card-resource.ts
+++ b/packages/host/app/resources/card-resource.ts
@@ -4,8 +4,6 @@
 
 import { registerDestructor } from '@ember/destroyable';
 import { getOwner } from '@ember/owner';
-import { buildWaiter } from '@ember/test-waiters';
-import { isTesting } from '@embroider/macros';
 import { tracked } from '@glimmer/tracking';
 
 import { restartableTask } from 'ember-concurrency';
@@ -18,7 +16,6 @@ import {
   apiFor,
   loaderFor,
   hasExecutableExtension,
-  type SingleCardDocument,
 } from '@cardstack/runtime-common';
 
 import { ErrorDetails } from '@cardstack/runtime-common/error';
@@ -55,7 +52,6 @@ interface Args {
   };
 }
 
-const waiter = buildWaiter('card-resource:load-card-waiter');
 const liveCards: WeakMap<
   Loader,
   Map<
@@ -275,33 +271,17 @@ export class CardResource extends Resource<Args> {
   }
 
   private reload = task(async (card: CardDef) => {
-    // we don't await this in the realm subscription callback, so this test
-    // waiter should catch otherwise leaky async in the tests
-    await this.withTestWaiters(async () => {
-      let incomingDoc: SingleCardDocument;
-      try {
-        incomingDoc = (await this.cardService.fetchJSON(
-          card.id,
-          undefined,
-        )) as SingleCardDocument;
-      } catch (err: any) {
-        if (err.status !== 404) {
-          throw err;
-        }
-        // in this case the document was invalidated in the index because the
-        // file was deleted
-        this.clearCardInstance();
-        return;
-      }
-
-      if (!isSingleCardDocument(incomingDoc)) {
-        throw new Error(
-          `bug: server returned a non card document for ${card.id}:
-        ${JSON.stringify(incomingDoc, null, 2)}`,
-        );
+    try {
+      await this.cardService.reloadCard(card);
+    } catch (err: any) {
+      if (err.status !== 404) {
+        throw err;
       }
-      await this.api.updateFromSerialized<typeof CardDef>(card, incomingDoc);
-    });
+      // in this case the document was invalidated in the index because the
+      // file was deleted
+      this.clearCardInstance();
+      return;
+    }
   });
 
   private unsubscribeFromRealm = () => {
@@ -315,21 +295,6 @@ export class CardResource extends Resource<Args> {
     }
   };
 
-  private async withTestWaiters<T>(cb: () => Promise<T>) {
-    let token = waiter.beginAsync();
-    try {
-      let result = await cb();
-      // only do this in test env--this makes sure that we also wait for any
-      // interior card instance async as part of our ember-test-waiters
-      if (isTesting()) {
-        await this.cardService.cardsSettled();
-      }
-      return result;
-    } finally {
-      waiter.endAsync(token);
-    }
-  }
-
   private async updateCardInstance(maybeCard: CardDef | undefined) {
     if (maybeCard) {
       this._api = await apiFor(maybeCard);
diff --git a/packages/host/app/services/card-service.ts b/packages/host/app/services/card-service.ts
index 1d43790d4c..78824f7035 100644
--- a/packages/host/app/services/card-service.ts
+++ b/packages/host/app/services/card-service.ts
@@ -1,6 +1,10 @@
 import type Owner from '@ember/owner';
 import Service, { service } from '@ember/service';
 
+import { buildWaiter } from '@ember/test-waiters';
+
+import { isTesting } from '@embroider/macros';
+
 import { stringify } from 'qs';
 
 import { v4 as uuidv4 } from 'uuid';
@@ -46,6 +50,8 @@ export type CardSaveSubscriber = (
 
 const { environment } = ENV;
 
+const waiter = buildWaiter('card-service:waiter');
+
 export default class CardService extends Service {
   @service private declare loaderService: LoaderService;
   @service private declare messageService: MessageService;
@@ -53,6 +59,21 @@ export default class CardService extends Service {
   @service private declare realm: Realm;
   @service private declare reset: ResetService;
 
+  private async withTestWaiters<T>(cb: () => Promise<T>) {
+    let token = waiter.beginAsync();
+    try {
+      let result = await cb();
+      // only do this in test env--this makes sure that we also wait for any
+      // interior card instance async as part of our ember-test-waiters
+      if (isTesting()) {
+        await this.cardsSettled();
+      }
+      return result;
+    } finally {
+      waiter.endAsync(token);
+    }
+  }
+
   private subscriber: CardSaveSubscriber | undefined;
   // For tracking requests during the duration of this service. Used for being able to tell when to ignore an incremental indexing SSE event.
   // We want to ignore it when it is a result of our own request so that we don't reload the card and overwrite any unsaved changes made during auto save request and SSE event.
@@ -155,10 +176,31 @@ export default class CardService extends Service {
     return serialized;
   }
 
+  async reloadCard(card: CardDef): Promise<void> {
+    // we don't await this in the realm subscription callback, so this test
+    // waiter should catch otherwise leaky async in the tests
+    await this.withTestWaiters(async () => {
+      let incomingDoc: SingleCardDocument = (await this.fetchJSON(
+        card.id,
+        undefined,
+      )) as SingleCardDocument;
+
+      if (!isSingleCardDocument(incomingDoc)) {
+        throw new Error(
+          `bug: server returned a non card document for ${card.id}:
+        ${JSON.stringify(incomingDoc, null, 2)}`,
+        );
+      }
+      let api = await this.getAPI();
+      await api.updateFromSerialized<typeof CardDef>(card, incomingDoc);
+    });
+  }
+
   // we return undefined if the card changed locally while the save was in-flight
   async saveModel<T extends object>(
     owner: T,
     card: CardDef,
+    defaultRealmHref?: string,
   ): Promise<CardDef | undefined> {
     let cardChanged = false;
     function onCardChange() {
@@ -179,10 +221,12 @@ export default class CardService extends Service {
       // in the case where we get no realm URL from the card, we are dealing with
       // a new card instance that does not have a realm URL yet.
       if (!realmURL) {
-        if (!this.realm.defaultWritableRealm) {
+        defaultRealmHref =
+          defaultRealmHref ?? this.realm.defaultWritableRealm?.path;
+        if (!defaultRealmHref) {
           throw new Error('Could not find a writable realm');
         }
-        realmURL = new URL(this.realm.defaultWritableRealm.path);
+        realmURL = new URL(defaultRealmHref);
       }
       let json = await this.saveCardDocument(doc, realmURL);
       let isNew = !card.id;
@@ -303,7 +347,7 @@ export default class CardService extends Service {
     return card;
   }
 
-  async getCard(url: URL | string): Promise<CardDef | undefined> {
+  async getCard(url: URL | string): Promise<CardDef> {
     if (typeof url === 'string') {
       url = new URL(url);
     }
diff --git a/packages/host/app/services/command-service.ts b/packages/host/app/services/command-service.ts
index 95bdb2a707..747c635ee6 100644
--- a/packages/host/app/services/command-service.ts
+++ b/packages/host/app/services/command-service.ts
@@ -1,13 +1,20 @@
+import { getOwner, setOwner } from '@ember/owner';
 import Service, { service } from '@ember/service';
 
 import { task } from 'ember-concurrency';
 
 import flatMap from 'lodash/flatMap';
 
+import { IEvent } from 'matrix-js-sdk';
+
+import { v4 as uuidv4 } from 'uuid';
+
 import {
+  Command,
   type LooseSingleCardDocument,
   type PatchData,
   baseRealm,
+  CommandContext,
 } from '@cardstack/runtime-common';
 import {
   type CardTypeFilter,
@@ -27,6 +34,8 @@ import type {
   CommandResultEvent,
 } from 'https://cardstack.com/base/matrix-event';
 
+import { shortenUuid } from '../utils/uuid';
+
 import CardService from './card-service';
 import RealmServerService from './realm-server';
 
@@ -37,23 +46,117 @@ export default class CommandService extends Service {
   @service private declare realm: Realm;
   @service private declare realmServer: RealmServerService;
 
+  private commands: Map<
+    string,
+    { command: Command<any, any, any>; autoExecute: boolean }
+  > = new Map();
+
+  public registerCommand(
+    command: Command<any, any, any>,
+    autoExecute: boolean,
+  ) {
+    let name = `${command.name}_${shortenUuid(uuidv4())}`; //TODO: use a short uuid here instead -- we need uniqueness across browser runtime instances
+    this.commands.set(name, { command, autoExecute });
+    return name;
+  }
+
+  public async executeCommandEventIfNeeded(event: Partial<IEvent>) {
+    // examine the tool_call and see if it's a command that we know how to run
+    let toolCall = event?.content?.data?.toolCall;
+    if (!toolCall) {
+      return;
+    }
+    // TODO: check whether this toolCall was already executed and exit if so
+    let { name } = toolCall;
+    let { command, autoExecute } = this.commands.get(name) ?? {};
+    if (!command || !autoExecute) {
+      return;
+    }
+    // Get the input type and validate/construct the payload
+    let InputType = await command.getInputType();
+
+    // Construct a new instance of the input type with the payload
+    let typedInput = new InputType({
+      ...toolCall.arguments.attributes,
+      ...toolCall.arguments.relationships,
+    });
+    await command.execute(typedInput);
+    await this.matrixService.sendReactionEvent(
+      event.room_id!,
+      event.event_id!,
+      'applied',
+    );
+  }
+
+  //TODO use create[CommandName] methods to create commands instead of lookupCommand to solve type issues and avoid embroider issues
+  //   OR
+  //TODO use imports and leverage with custom loader maybe import SaveCard from 'http://cardstack.com/host/commannds/save-card'
+  lookupCommand = <
+    CardInputType extends CardDef | undefined,
+    CardResultType extends CardDef | undefined,
+    CommandConfiguration extends any | undefined,
+  >(
+    name: string,
+    configuration: CommandConfiguration | undefined,
+  ): Command<CardInputType, CardResultType, CommandConfiguration> => {
+    let owner = getOwner(this)!;
+    let commandFactory = owner.factoryFor(`command:${name}`);
+    if (!commandFactory) {
+      throw new Error(`Could not find command "${name}"`);
+    }
+    let CommandClass = commandFactory.class as unknown as {
+      new (
+        commandContext: CommandContext,
+        commandConfiguration: CommandConfiguration | undefined,
+      ): Command<CardInputType, CardResultType, CommandConfiguration>;
+    };
+    let instance = new CommandClass(
+      this.commandContext,
+      configuration,
+    ) as Command<CardInputType, CardResultType, CommandConfiguration>;
+    setOwner(instance, owner);
+    return instance;
+  };
+
+  get commandContext(): CommandContext {
+    return {
+      lookupCommand: this.lookupCommand,
+      sendAiAssistantMessage: (
+        ...args: Parameters<MatrixService['sendAiAssistantMessage']>
+      ) => this.matrixService.sendAiAssistantMessage(...args),
+    };
+  }
+
   //TODO: Convert to non-EC async method after fixing CS-6987
   run = task(async (command: CommandCard, roomId: string) => {
     let { payload, eventId } = command;
     let res: any;
     try {
       this.matrixService.failedCommandState.delete(eventId);
-      if (command.name === 'patchCard') {
+
+      // lookup command
+      let { command: commandToRun } = this.commands.get(command.name) ?? {};
+
+      if (commandToRun) {
+        // Get the input type and validate/construct the payload
+        let InputType = await commandToRun.getInputType();
+        // Construct a new instance of the input type with the payload
+        let typedInput = new InputType({
+          ...payload.attributes,
+          ...payload.relationships,
+        });
+        res = await commandToRun.execute(typedInput);
+      } else if (command.name === 'patchCard') {
         if (!hasPatchData(payload)) {
           throw new Error(
             "Patch command can't run because it doesn't have all the fields in arguments returned by open ai",
           );
         }
         res = await this.operatorModeStateService.patchCard.perform(
-          payload.card_id,
+          payload?.attributes?.cardId,
           {
-            attributes: payload.attributes,
-            relationships: payload.relationships,
+            attributes: payload?.attributes?.patch?.attributes,
+            relationships: payload?.attributes?.patch?.relationships,
           },
         );
       } else if (command.name === 'searchCard') {
@@ -62,7 +165,7 @@ export default class CommandService extends Service {
             "Search command can't run because it doesn't have all the arguments returned by open ai",
           );
         }
-        let query = { filter: payload.filter };
+        let query = { filter: payload.attributes.filter };
         let realmUrls = this.realmServer.availableRealmURLs;
         let instances: CardDef[] = flatMap(
           await Promise.all(
@@ -171,23 +274,20 @@ export default class CommandService extends Service {
   }
 }
 
-type PatchPayload = { card_id: string } & PatchData;
-type SearchPayload = { card_id: string; filter: CardTypeFilter | EqFilter };
+type PatchPayload = { attributes: { cardId: string; patch: PatchData } };
+type SearchPayload = {
+  attributes: { cardId: string; filter: CardTypeFilter | EqFilter };
+};
 
 function hasPatchData(payload: any): payload is PatchPayload {
   return (
-    (typeof payload === 'object' &&
-      payload !== null &&
-      'card_id' in payload &&
-      'attributes' in payload) ||
-    (typeof payload === 'object' &&
-      payload !== null &&
-      'card_id' in payload &&
-      'relationships' in payload)
+    payload.attributes?.cardId &&
+    (payload.attributes?.patch?.attributes ||
+      payload.attributes?.patch?.relationships)
   );
 }
 
 function hasSearchData(payload: any): payload is SearchPayload {
-  assertQuery({ filter: payload.filter });
+  assertQuery({ filter: payload.attributes.filter });
   return payload;
 }
diff --git a/packages/host/app/services/matrix-service.ts b/packages/host/app/services/matrix-service.ts
index bfb160c9b5..da1057d1a6 100644
--- a/packages/host/app/services/matrix-service.ts
+++ b/packages/host/app/services/matrix-service.ts
@@ -31,10 +31,11 @@ import {
   loaderFor,
   LooseCardResource,
   ResolvedCodeRef,
+  Command,
 } from '@cardstack/runtime-common';
 import {
   basicMappings,
-  generateCardPatchCallSpecification,
+  generateJsonSchemaForCardType,
   getSearchTool,
   getGenerateAppModuleTool,
 } from '@cardstack/runtime-common/helpers/ai';
@@ -76,6 +77,7 @@ import { RoomResource, getRoom } from '../resources/room';
 import { type SerializedState as OperatorModeSerializedState } from './operator-mode-state-service';
 
 import type CardService from './card-service';
+import type CommandService from './command-service';
 import type LoaderService from './loader-service';
 import type MatrixSDKLoader from './matrix-sdk-loader';
 import type { ExtendedClient, ExtendedMatrixSDK } from './matrix-sdk-loader';
@@ -104,6 +106,7 @@ export type OperatorModeContext = {
 export default class MatrixService extends Service {
   @service private declare loaderService: LoaderService;
   @service private declare cardService: CardService;
+  @service private declare commandService: CommandService;
   @service private declare realm: RealmService;
   @service private declare matrixSdkLoader: MatrixSDKLoader;
   @service private declare realmServer: RealmServerService;
@@ -116,6 +119,7 @@ export default class MatrixService extends Service {
   profile = getMatrixProfile(this, () => this.client.getUserId());
 
   private rooms: TrackedMap<string, RoomState> = new TrackedMap();
+
   roomResourcesCache: TrackedMap<string, RoomResource> = new TrackedMap();
   messagesToSend: TrackedMap<string, string | undefined> = new TrackedMap();
   cardsToSend: TrackedMap<string, CardDef[] | undefined> = new TrackedMap();
@@ -583,7 +587,7 @@ export default class MatrixService extends Service {
       );
       // Generate tool calls for patching currently open cards permitted for modification
       for (let attachedOpenCard of attachedOpenCards) {
-        let patchSpec = generateCardPatchCallSpecification(
+        let patchSpec = generateJsonSchemaForCardType(
           attachedOpenCard.constructor as typeof CardDef,
           this.cardAPI,
           mappings,
@@ -627,6 +631,73 @@ export default class MatrixService extends Service {
     } as CardMessageContent);
   }
 
+  public async sendAiAssistantMessage(params: {
+    roomId?: string; // if falsy we create a new room
+    show?: boolean; // if truthy, ensure the side panel to the room
+    prompt: string;
+    attachedCards?: CardDef[];
+    skillCards?: SkillCard[];
+    commands?: { command: Command<any, any, any>; autoExecute: boolean }[];
+  }): Promise<{ roomId: string }> {
+    let roomId = params.roomId;
+    if (!roomId) {
+      roomId = await this.createRoom('AI Assistant', [aiBotUsername]);
+    }
+
+    let html = markdownToHtml(params.prompt);
+    let mappings = await basicMappings(this.loaderService.loader);
+    let tools = [];
+    for (let { command, autoExecute } of params.commands ?? []) {
+      // get a registered name for the command
+      let name = this.commandService.registerCommand(command, autoExecute);
+      tools.push({
+        type: 'function',
+        function: {
+          name,
+          description: command.description,
+          parameters: {
+            type: 'object',
+            properties: await command.getInputJsonSchema(
+              this.cardAPI,
+              mappings,
+            ),
+          },
+        },
+      });
+    }
+
+    let attachedCardsEventIds = await this.getCardEventIds(
+      params.attachedCards ?? [],
+      roomId,
+      this.cardHashes,
+      { maybeRelativeURL: null },
+    );
+    let attachedSkillEventIds = await this.getCardEventIds(
+      params.skillCards ?? [],
+      roomId,
+      this.skillCardHashes,
+      { includeComputeds: true, maybeRelativeURL: null },
+    );
+
+    let clientGeneratedId = uuidv4();
+
+    await this.sendEvent(roomId, 'm.room.message', {
+      msgtype: 'org.boxel.message',
+      body: params.prompt || '',
+      format: 'org.matrix.custom.html',
+      formatted_body: html,
+      clientGeneratedId,
+      data: {
+        attachedCardsEventIds,
+        attachedSkillEventIds,
+        context: {
+          tools,
+        },
+      },
+    } as CardMessageContent);
+    return { roomId };
+  }
+
   private generateCardHashKey(roomId: string, card: LooseSingleCardDocument) {
     return md5(roomId + JSON.stringify(card));
   }
@@ -813,23 +884,17 @@ export default class MatrixService extends Service {
     return card;
   }
 
-  private addRoomEvent(event: TempEvent) {
+  private addRoomEvent(event: TempEvent, oldEventId?: string) {
     let { event_id: eventId, room_id: roomId, state_key: stateKey } = event;
     // If we are receiving an event which contains
-    // a data field, we need to parse it
+    // a data field, we may need to parse it
     // because matrix doesn't support all json types
     // Corresponding encoding is done in
     // sendEvent in the matrix-service
     if (event.content?.data) {
-      if (typeof event.content.data !== 'string') {
-        console.warn(
-          `skipping matrix event ${
-            eventId ?? stateKey
-          }, event.content.data is not serialized properly`,
-        );
-        return;
+      if (typeof event.content.data === 'string') {
+        event.content.data = JSON.parse(event.content.data);
       }
-      event.content.data = JSON.parse(event.content.data);
     }
     eventId = eventId ?? stateKey; // room state may not necessary have an event ID
     if (!eventId) {
@@ -853,12 +918,25 @@ export default class MatrixService extends Service {
     }
 
     // duplicate events may be emitted from matrix, as well as the resolved room card might already contain this event
-    if (!room.events.find((e) => e.event_id === eventId)) {
+    let matchingEvents = room.events.filter(
+      (e) => e.event_id === eventId || e.event_id === oldEventId,
+    );
+    if (matchingEvents.length > 1) {
+      throw new Error(
+        `bug: ${matchingEvents.length} events with the same event_id(s): ${eventId}, ${oldEventId}, expected a maximum of 1`,
+      );
+    }
+    if (matchingEvents.length === 0) {
       room.events = [
         ...(room.events ?? []),
         event as unknown as DiscreteMatrixEvent,
       ];
+      return;
     }
+    let eventToReplace = matchingEvents[0];
+    let eventIndex = room.events.indexOf(eventToReplace);
+    room.events[eventIndex] = event as unknown as DiscreteMatrixEvent;
+    room.events = [...room.events];
   }
 
   private onMembership = (event: MatrixEvent, member: RoomMember) => {
@@ -965,9 +1043,6 @@ export default class MatrixService extends Service {
     _room: unknown,
     maybeOldEventId?: string,
   ) => {
-    if (typeof maybeOldEventId !== 'string') {
-      return;
-    }
     this.timelineQueue.push({ event: e, oldEventId: maybeOldEventId });
     debounce(this, this.drainTimeline, 100);
   };
@@ -1088,10 +1163,13 @@ export default class MatrixService extends Service {
         }
       }
     }
-    if (oldEventId) {
-      await this.updateRoomEvent(event, oldEventId);
-    } else {
-      await this.addRoomEvent(event);
+    await this.addRoomEvent(event, oldEventId);
+
+    if (
+      event.type === 'm.room.message' &&
+      event.content?.msgtype === 'org.boxel.command'
+    ) {
+      this.commandService.executeCommandEventIfNeeded(event);
     }
 
     if (room.oldState.paginationToken != null) {
@@ -1099,40 +1177,6 @@ export default class MatrixService extends Service {
       await this.client?.scrollback(room);
     }
   }
-
-  private async updateRoomEvent(event: Partial<IEvent>, oldEventId: string) {
-    if (event.content?.data && typeof event.content.data === 'string') {
-      event.content.data = JSON.parse(event.content.data);
-    }
-    let { event_id: eventId, room_id: roomId, state_key: stateKey } = event;
-    eventId = eventId ?? stateKey; // room state may not necessary have an event ID
-    if (!eventId) {
-      throw new Error(
-        `bug: event ID is undefined for event ${JSON.stringify(
-          event,
-          null,
-          2,
-        )}`,
-      );
-    }
-    if (!roomId) {
-      throw new Error(
-        `bug: roomId is undefined for event ${JSON.stringify(event, null, 2)}`,
-      );
-    }
-
-    let room = this.getRoom(roomId);
-    if (!room) {
-      throw new Error(
-        `bug: unknown room for event ${JSON.stringify(event, null, 2)}`,
-      );
-    }
-    let oldEventIndex = room.events.findIndex((e) => e.event_id === oldEventId);
-    if (oldEventIndex >= 0) {
-      room.events[oldEventIndex] = event as unknown as DiscreteMatrixEvent;
-      room.events = [...room.events];
-    }
-  }
 }
 
 function saveAuth(auth: LoginResponse) {
diff --git a/packages/host/app/services/operator-mode-state-service.ts b/packages/host/app/services/operator-mode-state-service.ts
index 2fdc47f8ef..42428e92bd 100644
--- a/packages/host/app/services/operator-mode-state-service.ts
+++ b/packages/host/app/services/operator-mode-state-service.ts
@@ -126,35 +126,36 @@ export default class OperatorModeStateService extends Service {
   }
 
   patchCard = task({ enqueue: true }, async (id: string, patch: PatchData) => {
-    let stackItems = this.state?.stacks.flat() ?? [];
-    if (
-      !stackItems.length ||
-      !this.topMostStackItems().some((item) => item.card.id == id)
-    ) {
-      throw new Error(`Please open card '${id}' to make changes to it.`);
+    let card = await this.cardService.getCard(id);
+    let document = await this.cardService.serializeCard(card);
+    if (patch.attributes) {
+      document.data.attributes = mergeWith(
+        document.data.attributes,
+        patch.attributes,
+      );
+    }
+    if (patch.relationships) {
+      let mergedRel = mergeRelationships(
+        document.data.relationships,
+        patch.relationships,
+      );
+      if (mergedRel && Object.keys(mergedRel).length !== 0) {
+        document.data.relationships = mergedRel;
+      }
     }
+    await this.cardService.patchCard(card, document, patch);
+    // TODO: if we introduce an identity map, we would not need this
+    await this.reloadCardIfOpen(card.id);
+  });
+
+  async reloadCardIfOpen(id: string) {
+    let stackItems = this.state?.stacks.flat() ?? [];
     for (let item of stackItems) {
       if ('card' in item && item.card.id == id) {
-        let document = await this.cardService.serializeCard(item.card);
-        if (patch.attributes) {
-          document.data.attributes = mergeWith(
-            document.data.attributes,
-            patch.attributes,
-          );
-        }
-        if (patch.relationships) {
-          let mergedRel = mergeRelationships(
-            document.data.relationships,
-            patch.relationships,
-          );
-          if (mergedRel && Object.keys(mergedRel).length !== 0) {
-            document.data.relationships = mergedRel;
-          }
-        }
-        await this.cardService.patchCard(item.card, document, patch);
+        this.cardService.reloadCard(item.card);
       }
     }
-  });
+  }
 
   async deleteCard(card: CardDef) {
     // remove all stack items for the deleted card
@@ -448,6 +449,21 @@ export default class OperatorModeStateService extends Service {
     return stringify(this.rawStateWithSavedCardsOnly())!;
   }
 
+  async createStackItem(
+    card: CardDef,
+    stackIndex: number,
+    format: 'isolated' | 'edit' = 'isolated',
+  ) {
+    let stackItem = new StackItem({
+      card,
+      stackIndex,
+      owner: this,
+      format,
+    });
+    await stackItem.ready();
+    return stackItem;
+  }
+
   // Deserialize a stringified JSON version of OperatorModeState into a Glimmer tracked object
   // so that templates can react to changes in stacks and their items
   async deserialize(rawState: SerializedState): Promise<OperatorModeState> {
diff --git a/packages/host/app/utils/uuid.ts b/packages/host/app/utils/uuid.ts
new file mode 100644
index 0000000000..c1fd61a263
--- /dev/null
+++ b/packages/host/app/utils/uuid.ts
@@ -0,0 +1,13 @@
+const flickrBase58 =
+  '123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ';
+
+export function shortenUuid(v4Uuid: string): string {
+  // shorten it using flickrBase58
+  let num = BigInt('0x' + v4Uuid.replace(/-/g, ''));
+  let shortUuid = '';
+  while (num > 0) {
+    shortUuid = flickrBase58[Number(num % 58n)] + shortUuid;
+    num /= 58n;
+  }
+  return shortUuid;
+}
diff --git a/packages/host/tests/acceptance/commands-test.gts b/packages/host/tests/acceptance/commands-test.gts
new file mode 100644
index 0000000000..dbaa2c0cde
--- /dev/null
+++ b/packages/host/tests/acceptance/commands-test.gts
@@ -0,0 +1,586 @@
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { getOwner, setOwner } from '@ember/owner';
+import { service } from '@ember/service';
+import { click, waitFor, findAll, waitUntil } from '@ember/test-helpers';
+
+import { module, test } from 'qunit';
+
+import { GridContainer } from '@cardstack/boxel-ui/components';
+
+import { baseRealm, Command } from '@cardstack/runtime-common';
+
+import type LoaderService from '@cardstack/host/services/loader-service';
+
+import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
+
+import type {
+  SwitchSubmodeInput,
+  SaveCardInput,
+  ShowCardInput,
+  PatchCardInput,
+} from 'https://cardstack.com/base/command';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import {
+  setupLocalIndexing,
+  setupServerSentEvents,
+  setupOnSave,
+  testRealmURL,
+  setupAcceptanceTestRealm,
+  visitOperatorMode,
+  delay,
+} from '../helpers';
+
+import {
+  CardDef,
+  Component,
+  CardsGrid,
+  contains,
+  linksTo,
+  linksToMany,
+  field,
+  setupBaseRealm,
+  StringField,
+} from '../helpers/base-realm';
+
+import { setupMockMatrix } from '../helpers/mock-matrix';
+import { setupApplicationTest } from '../helpers/setup';
+
+module('Acceptance | Commands tests', function (hooks) {
+  setupApplicationTest(hooks);
+  setupLocalIndexing(hooks);
+  setupServerSentEvents(hooks);
+  setupOnSave(hooks);
+  let { simulateRemoteMessage, getRoomIds, getRoomEvents } = setupMockMatrix(
+    hooks,
+    {
+      loggedInAs: '@testuser:staging',
+      activeRealms: [baseRealm.url, testRealmURL],
+    },
+  );
+  setupBaseRealm(hooks);
+
+  hooks.beforeEach(async function () {
+    class Pet extends CardDef {
+      static displayName = 'Pet';
+      @field name = contains(StringField);
+      @field favoriteTreat = contains(StringField);
+
+      @field title = contains(StringField, {
+        computeVia: function (this: Pet) {
+          return this.name;
+        },
+      });
+      static embedded = class Embedded extends Component<typeof this> {
+        <template>
+          <h3 data-test-pet={{@model.name}}>
+            <@fields.name />
+          </h3>
+        </template>
+      };
+      static isolated = class Isolated extends Component<typeof this> {
+        <template>
+          <GridContainer class='container'>
+            <h2><@fields.title /></h2>
+            <div>
+              <div>Favorite Treat: <@fields.favoriteTreat /></div>
+              <div data-test-editable-meta>
+                {{#if @canEdit}}
+                  <@fields.title />
+                  is editable.
+                {{else}}
+                  <@fields.title />
+                  is NOT editable.
+                {{/if}}
+              </div>
+            </div>
+          </GridContainer>
+        </template>
+      };
+    }
+
+    class ScheduleMeetingInput extends CardDef {
+      @field topic = contains(StringField);
+      @field participants = linksToMany(() => Person);
+    }
+
+    class Meeting extends CardDef {
+      static displayName = 'Meeting';
+      @field participants = linksToMany(() => Person);
+      @field topic = contains(StringField);
+    }
+
+    class ScheduleMeetingCommand extends Command<
+      ScheduleMeetingInput,
+      undefined
+    > {
+      @service private declare loaderService: LoaderService;
+      @service
+      private declare operatorModeStateService: OperatorModeStateService;
+      static displayName = 'ScheduleMeetingCommand';
+
+      async getInputType() {
+        return ScheduleMeetingInput;
+      }
+      protected async run(input: ScheduleMeetingInput) {
+        let meeting = new Meeting({
+          topic: 'unset topic',
+          participants: input.participants,
+        });
+        let saveCardCommand = this.commandContext.lookupCommand<
+          SaveCardInput,
+          undefined
+        >('save-card');
+        const { SaveCardInput } = await this.loaderService.loader.import<
+          typeof BaseCommandModule
+        >(`${baseRealm.url}command`);
+        await saveCardCommand.execute(
+          new SaveCardInput({
+            card: meeting,
+            realm: testRealmURL,
+          }),
+        );
+
+        // Mutate and save again
+        let patchCardCommand = this.commandContext.lookupCommand<
+          PatchCardInput,
+          undefined,
+          { cardType: typeof Meeting }
+        >('patch-card', { cardType: Meeting });
+
+        await this.commandContext.sendAiAssistantMessage({
+          prompt: `Change the topic of the meeting to "${input.topic}"`,
+          attachedCards: [meeting],
+          commands: [{ command: patchCardCommand, autoExecute: true }],
+        });
+
+        await patchCardCommand.waitForNextCompletion();
+
+        let showCardCommand = this.commandContext.lookupCommand<
+          ShowCardInput,
+          undefined
+        >('show-card');
+        const { ShowCardInput } = await this.loaderService.loader.import<
+          typeof BaseCommandModule
+        >(`${baseRealm.url}command`);
+        await showCardCommand.execute(
+          new ShowCardInput({
+            cardToShow: meeting,
+            placement: 'addToStack',
+          }),
+        );
+
+        return undefined;
+      }
+    }
+
+    class Person extends CardDef {
+      static displayName = 'Person';
+      @field firstName = contains(StringField);
+      @field lastName = contains(StringField);
+      @field pet = linksTo(Pet);
+      @field friends = linksToMany(Pet);
+      @field firstLetterOfTheName = contains(StringField, {
+        computeVia: function (this: Person) {
+          if (!this.firstName) {
+            return;
+          }
+          return this.firstName[0];
+        },
+      });
+      @field title = contains(StringField, {
+        computeVia: function (this: Person) {
+          return [this.firstName, this.lastName].filter(Boolean).join(' ');
+        },
+      });
+
+      static isolated = class Isolated extends Component<typeof this> {
+        runSwitchToCodeModeCommandViaAiAssistant = (autoExecute: boolean) => {
+          let commandContext = this.args.context?.commandContext;
+          if (!commandContext) {
+            console.error('No command context found');
+            return;
+          }
+          let switchSubmodeCommand = commandContext.lookupCommand<
+            SwitchSubmodeInput,
+            undefined
+          >('switch-submode');
+          commandContext.sendAiAssistantMessage({
+            prompt: 'Switch to code mode',
+            commands: [{ command: switchSubmodeCommand, autoExecute }],
+          });
+        };
+        runScheduleMeetingCommand = async () => {
+          let commandContext = this.args.context?.commandContext;
+          if (!commandContext) {
+            console.error('No command context found');
+            return;
+          }
+          let scheduleMeeting = new ScheduleMeetingCommand(
+            commandContext,
+            undefined,
+          );
+          setOwner(scheduleMeeting, getOwner(this)!);
+          await scheduleMeeting.execute(
+            new ScheduleMeetingInput({
+              topic: 'Meeting with Hassan',
+              participants: [this.args.model],
+            }),
+          );
+        };
+        <template>
+          <h2 data-test-person={{@model.firstName}}>
+            <@fields.firstName />
+          </h2>
+          <p data-test-first-letter-of-the-name={{@model.firstLetterOfTheName}}>
+            <@fields.firstLetterOfTheName />
+          </p>
+          Pet:
+          <@fields.pet />
+          Friends:
+          <@fields.friends />
+          <button
+            {{on
+              'click'
+              (fn this.runSwitchToCodeModeCommandViaAiAssistant true)
+            }}
+            data-test-switch-to-code-mode-with-autoexecute-button
+          >Switch to code-mode with autoExecute</button>
+          <button
+            {{on
+              'click'
+              (fn this.runSwitchToCodeModeCommandViaAiAssistant false)
+            }}
+            data-test-switch-to-code-mode-without-autoexecute-button
+          >Switch to code-mode (no autoExecute)</button>
+          <button
+            {{on 'click' this.runScheduleMeetingCommand}}
+            data-test-schedule-meeting-button
+          >Schedule meeting</button>
+        </template>
+      };
+    }
+    let mangoPet = new Pet({ name: 'Mango' });
+
+    await setupAcceptanceTestRealm({
+      contents: {
+        'person.gts': { Person, Meeting },
+        'pet.gts': { Pet },
+        'Pet/ringo.json': new Pet({ name: 'Ringo' }),
+        'Person/hassan.json': new Person({
+          firstName: 'Hassan',
+          lastName: 'Abdel-Rahman',
+          pet: mangoPet,
+          friends: [mangoPet],
+        }),
+        'Pet/mango.json': mangoPet,
+        'Pet/vangogh.json': new Pet({ name: 'Van Gogh' }),
+        'Person/fadhlan.json': new Person({
+          firstName: 'Fadhlan',
+          pet: mangoPet,
+          friends: [mangoPet],
+        }),
+        'index.json': new CardsGrid(),
+        '.realm.json': {
+          name: 'Test Workspace B',
+          backgroundURL:
+            'https://i.postimg.cc/VNvHH93M/pawel-czerwinski-Ly-ZLa-A5jti-Y-unsplash.jpg',
+          iconURL: 'https://i.postimg.cc/L8yXRvws/icon.png',
+        },
+      },
+    });
+  });
+
+  test('a command sent via sendAiAssistantMessage with autoExecute flag is automatically executed by the bot', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: `${testRealmURL}index`,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+    const testCard = `${testRealmURL}Person/hassan`;
+
+    await click('[data-test-boxel-filter-list-button="All Cards"]');
+    await click(
+      `[data-test-stack-card="${testRealmURL}index"] [data-test-cards-grid-item="${testCard}"]`,
+    );
+    await click('[data-test-switch-to-code-mode-with-autoexecute-button]');
+    await waitUntil(() => getRoomIds().length > 0);
+    let roomId = getRoomIds()[0];
+    let message = getRoomEvents(roomId).pop()!;
+    assert.strictEqual(message.content.msgtype, 'org.boxel.message');
+    let boxelMessageData = message.content.data;
+    assert.strictEqual(boxelMessageData.context.tools.length, 1);
+    assert.strictEqual(boxelMessageData.context.tools[0].type, 'function');
+    let toolName = boxelMessageData.context.tools[0].function.name;
+    assert.ok(
+      /^SwitchSubmodeCommand_/.test(toolName),
+      'The function name start with SwitchSubmodeCommand_',
+    );
+    assert.strictEqual(
+      boxelMessageData.context.tools[0].function.description,
+      'Navigate the UI to another submode. Possible values for submode are "interact" and "code".',
+    );
+    // TODO: do we need to include `required: ['attributes'],` in the parameters object? If so, how?
+    assert.deepEqual(boxelMessageData.context.tools[0].function.parameters, {
+      type: 'object',
+      properties: {
+        attributes: {
+          type: 'object',
+          properties: {
+            submode: {
+              type: 'string',
+            },
+            title: {
+              type: 'string',
+            },
+            description: {
+              type: 'string',
+            },
+            thumbnailURL: {
+              type: 'string',
+            },
+          },
+        },
+        relationships: {
+          properties: {},
+          type: 'object',
+        },
+      },
+    });
+    simulateRemoteMessage(roomId, '@aibot:localhost', {
+      body: 'Switching to code submode',
+      msgtype: 'org.boxel.command',
+      formatted_body: 'Switching to code submode',
+      format: 'org.matrix.custom.html',
+      data: JSON.stringify({
+        toolCall: {
+          name: toolName,
+          arguments: {
+            attributes: {
+              submode: 'code',
+            },
+          },
+        },
+        eventId: '__EVENT_ID__',
+      }),
+      'm.relates_to': {
+        rel_type: 'm.replace',
+        event_id: '__EVENT_ID__',
+      },
+    });
+    await waitFor('[data-test-submode-switcher=code]');
+    assert.dom('[data-test-submode-switcher=code]').exists();
+    assert.dom('[data-test-card-url-bar-input]').hasValue(`${testCard}.json`);
+    await click('[data-test-submode-switcher] button');
+    await click('[data-test-boxel-menu-item-text="Interact"]');
+    await click('[data-test-open-ai-assistant]');
+    assert
+      .dom(
+        '[data-test-message-idx="0"][data-test-boxel-message-from="testuser"]',
+      )
+      .containsText('Switch to code mode');
+    assert
+      .dom('[data-test-message-idx="1"][data-test-boxel-message-from="aibot"]')
+      .containsText('Switching to code submode');
+    assert
+      .dom('[data-test-message-idx="1"] [data-test-apply-state="applied"]')
+      .exists();
+  });
+
+  test('a command sent via sendAiAssistantMessage without autoExecute flag is not automatically executed by the bot', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: `${testRealmURL}index`,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+    const testCard = `${testRealmURL}Person/hassan`;
+
+    await click('[data-test-boxel-filter-list-button="All Cards"]');
+    await click(
+      `[data-test-stack-card="${testRealmURL}index"] [data-test-cards-grid-item="${testCard}"]`,
+    );
+    await click('[data-test-switch-to-code-mode-without-autoexecute-button]');
+    await waitUntil(() => getRoomIds().length > 0);
+    let roomId = getRoomIds()[0];
+    let message = getRoomEvents(roomId).pop()!;
+    assert.strictEqual(message.content.msgtype, 'org.boxel.message');
+    let boxelMessageData = message.content.data;
+    assert.strictEqual(boxelMessageData.context.tools.length, 1);
+    assert.strictEqual(boxelMessageData.context.tools[0].type, 'function');
+    let toolName = boxelMessageData.context.tools[0].function.name;
+    assert.ok(
+      /^SwitchSubmodeCommand_/.test(toolName),
+      'The function name start with SwitchSubmodeCommand_',
+    );
+    assert.strictEqual(
+      boxelMessageData.context.tools[0].function.description,
+      'Navigate the UI to another submode. Possible values for submode are "interact" and "code".',
+    );
+    // TODO: do we need to include `required: ['attributes'],` in the parameters object? If so, how?
+    assert.deepEqual(boxelMessageData.context.tools[0].function.parameters, {
+      type: 'object',
+      properties: {
+        attributes: {
+          type: 'object',
+          properties: {
+            submode: {
+              type: 'string',
+            },
+            title: {
+              type: 'string',
+            },
+            description: {
+              type: 'string',
+            },
+            thumbnailURL: {
+              type: 'string',
+            },
+          },
+        },
+        relationships: {
+          properties: {},
+          type: 'object',
+        },
+      },
+    });
+    simulateRemoteMessage(roomId, '@aibot:localhost', {
+      body: 'Switching to code submode',
+      msgtype: 'org.boxel.command',
+      formatted_body: 'Switching to code submode',
+      format: 'org.matrix.custom.html',
+      data: JSON.stringify({
+        toolCall: {
+          name: toolName,
+          arguments: {
+            attributes: {
+              submode: 'code',
+            },
+          },
+        },
+        eventId: '__EVENT_ID__',
+      }),
+      'm.relates_to': {
+        rel_type: 'm.replace',
+        event_id: '__EVENT_ID__',
+      },
+    });
+    await delay(500);
+    assert.dom('[data-test-submode-switcher=interact]').exists();
+    await click('[data-test-open-ai-assistant]');
+    assert
+      .dom(
+        '[data-test-message-idx="0"][data-test-boxel-message-from="testuser"]',
+      )
+      .containsText('Switch to code mode');
+    assert
+      .dom('[data-test-message-idx="1"][data-test-boxel-message-from="aibot"]')
+      .containsText('Switching to code submode');
+    assert
+      .dom('[data-test-message-idx="1"] [data-test-apply-state="ready"]')
+      .exists();
+    await click('[data-test-message-idx="1"] [data-test-command-apply]');
+    await waitFor('[data-test-submode-switcher=code]');
+    assert.dom('[data-test-submode-switcher=code]').exists();
+    assert.dom('[data-test-card-url-bar-input]').hasValue(`${testCard}.json`);
+    await click('[data-test-submode-switcher] button');
+    await click('[data-test-boxel-menu-item-text="Interact"]');
+    await click('[data-test-open-ai-assistant]');
+    assert
+      .dom(
+        '[data-test-message-idx="0"][data-test-boxel-message-from="testuser"]',
+      )
+      .containsText('Switch to code mode');
+    assert
+      .dom('[data-test-message-idx="1"][data-test-boxel-message-from="aibot"]')
+      .containsText('Switching to code submode');
+    assert
+      .dom('[data-test-message-idx="1"] [data-test-apply-state="applied"]')
+      .exists();
+  });
+
+  test('a scripted command can create a card, update it and show it', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: `${testRealmURL}index`,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+    const testCard = `${testRealmURL}Person/hassan`;
+
+    await click('[data-test-boxel-filter-list-button="All Cards"]');
+    await click(
+      `[data-test-stack-card="${testRealmURL}index"] [data-test-cards-grid-item="${testCard}"]`,
+    );
+    await click('[data-test-schedule-meeting-button]');
+    await waitUntil(() => getRoomIds().length > 0);
+    let roomId = getRoomIds()[0];
+    let message = getRoomEvents(roomId).pop()!;
+    assert.strictEqual(message.content.msgtype, 'org.boxel.message');
+    let boxelMessageData = message.content.data;
+    assert.strictEqual(boxelMessageData.context.tools.length, 1);
+    assert.strictEqual(boxelMessageData.context.tools[0].type, 'function');
+    let toolName = boxelMessageData.context.tools[0].function.name;
+    let meetingCardEventId = boxelMessageData.attachedCardsEventIds[0];
+    let cardFragment = getRoomEvents(roomId).find(
+      (event) => event.event_id === meetingCardEventId,
+    )!.content.data.cardFragment;
+
+    let parsedCard = JSON.parse(cardFragment);
+    let meetingCardId = parsedCard.data.id;
+
+    simulateRemoteMessage(roomId, '@aibot:localhost', {
+      body: 'Update card',
+      msgtype: 'org.boxel.command',
+      formatted_body: 'Update card',
+      format: 'org.matrix.custom.html',
+      data: JSON.stringify({
+        toolCall: {
+          name: toolName,
+          arguments: {
+            attributes: {
+              cardId: meetingCardId,
+              patch: {
+                attributes: {
+                  topic: 'Meeting with Hassan',
+                },
+              },
+            },
+          },
+        },
+        eventId: '__EVENT_ID__',
+      }),
+      'm.relates_to': {
+        rel_type: 'm.replace',
+        event_id: '__EVENT_ID__',
+      },
+    });
+
+    await waitUntil(
+      () => findAll('[data-test-operator-mode-stack]').length === 2,
+    );
+
+    assert.dom('[data-test-operator-mode-stack]').exists({ count: 2 });
+
+    assert
+      .dom(
+        '[data-test-operator-mode-stack="1"] [data-test-stack-card-index="0"]',
+      )
+      .includesText('Meeting with Hassan');
+  });
+});
diff --git a/packages/host/tests/cards/person.gts b/packages/host/tests/cards/person.gts
index bf65a32f6c..499df65f63 100644
--- a/packages/host/tests/cards/person.gts
+++ b/packages/host/tests/cards/person.gts
@@ -1,3 +1,5 @@
+import { on } from '@ember/modifier';
+
 import {
   contains,
   field,
@@ -5,6 +7,7 @@ import {
   CardDef,
   FieldDef,
 } from 'https://cardstack.com/base/card-api';
+import { SwitchSubmodeInput } from 'https://cardstack.com/base/command';
 import NumberCard from 'https://cardstack.com/base/number';
 import StringCard from 'https://cardstack.com/base/string';
 
@@ -26,9 +29,28 @@ export class Person extends CardDef {
   @field description = contains(StringCard, { computeVia: () => 'Person' });
 
   static isolated = class Isolated extends Component<typeof this> {
+    runSwitchToCodeModeCommandViaAiAssistant = () => {
+      let commandContext = this.args.context?.commandContext;
+      if (!commandContext) {
+        console.error('No command context found');
+        return;
+      }
+      let switchSubmodeCommand = commandContext.lookupCommand<
+        SwitchSubmodeInput,
+        undefined
+      >('switch-submode');
+      commandContext.sendAiAssistantMessage({
+        prompt: 'Switch to code mode',
+        commands: [{ command: switchSubmodeCommand, autoExecute: true }],
+      });
+    };
     <template>
       <h1><@fields.firstName /></h1>
       <h1><@fields.title /></h1>
+      <button
+        {{on 'click' this.runSwitchToCodeModeCommandViaAiAssistant}}
+        data-test-switch-to-code-mode-button
+      >Switch to code-mode</button>
     </template>
   };
   static embedded = class Embedded extends Component<typeof this> {
diff --git a/packages/host/tests/helpers/index.gts b/packages/host/tests/helpers/index.gts
index 563de70e21..05b28a8138 100644
--- a/packages/host/tests/helpers/index.gts
+++ b/packages/host/tests/helpers/index.gts
@@ -465,6 +465,11 @@ export function lookupLoaderService(): LoaderService {
   return owner.lookup('service:loader-service') as LoaderService;
 }
 
+export function lookupService<T extends Service>(name: string): T {
+  let owner = (getContext() as TestContext).owner;
+  return owner.lookup(`service:${name}`) as T;
+}
+
 export function lookupNetworkService(): NetworkService {
   let owner = (getContext() as TestContext).owner;
   return owner.lookup('service:network') as NetworkService;
diff --git a/packages/host/tests/helpers/mock-matrix/_client.ts b/packages/host/tests/helpers/mock-matrix/_client.ts
index fa7ed33986..2c75925929 100644
--- a/packages/host/tests/helpers/mock-matrix/_client.ts
+++ b/packages/host/tests/helpers/mock-matrix/_client.ts
@@ -313,6 +313,16 @@ export class MockClient implements ExtendedClient {
     if (content.body?.match(/SENDING_DELAY_THEN_/)) {
       await new Promise((resolve) => setTimeout(resolve, 1000));
     }
+
+    if (content.body?.match(/SENDING_DELAY_THEN_FAILURE/)) {
+      console.log(
+        'SENDING_DELAY_THEN_FAILURE, setting status to NOT_SENT',
+        localEvent,
+      );
+      localEvent.setStatus(MatrixSDK.EventStatus.NOT_SENT);
+      this.emitLocalEchoUpdated(localEvent);
+      throw new Error('Failed to send event, deliberately');
+    }
     let eventId = this.serverState.addRoomEvent(
       this.loggedInAs || 'unknown_user',
       roomEvent,
@@ -321,9 +331,7 @@ export class MockClient implements ExtendedClient {
       ...localEventData,
       event_id: eventId,
     });
-    if (content.body?.match(/SENDING_DELAY_THEN_FAILURE/)) {
-      matrixEvent.setStatus(MatrixSDK.EventStatus.NOT_SENT);
-    }
+
     this.emitLocalEchoUpdated(matrixEvent, localEventId);
     return { event_id: eventId };
   }
diff --git a/packages/host/tests/helpers/mock-matrix/_server-state.ts b/packages/host/tests/helpers/mock-matrix/_server-state.ts
index 4c7f8967e3..82c8ed1426 100644
--- a/packages/host/tests/helpers/mock-matrix/_server-state.ts
+++ b/packages/host/tests/helpers/mock-matrix/_server-state.ts
@@ -113,6 +113,7 @@ export class ServerState {
     >,
     overrides?: { state_key?: string; origin_server_ts?: number },
   ) {
+    // duplicate the event fully
     let room = event.room_id && this.#rooms.get(event.room_id);
     if (!room) {
       throw new Error(`room ${event.room_id} does not exist`);
@@ -137,8 +138,9 @@ export class ServerState {
       relatesTo.event_id = relatesTo.event_id.replace(/__EVENT_ID__/g, eventId);
     }
     room.events.push(matrixEvent);
-    this.#listeners.forEach((listener) => listener(matrixEvent));
-
+    setTimeout(() => {
+      this.#listeners.forEach((listener) => listener(matrixEvent));
+    }, 0);
     return matrixEvent.event_id;
   }
 
@@ -224,7 +226,7 @@ export class ServerState {
     if (!room) {
       throw new Error(`room ${roomId} does not exist`);
     }
-    return room.events;
+    return [...room.events];
   }
 
   eventId(): string {
diff --git a/packages/host/tests/helpers/mock-matrix/_utils.ts b/packages/host/tests/helpers/mock-matrix/_utils.ts
index 41210b7861..ca1bb2bb8f 100644
--- a/packages/host/tests/helpers/mock-matrix/_utils.ts
+++ b/packages/host/tests/helpers/mock-matrix/_utils.ts
@@ -14,6 +14,9 @@ export class MockUtils {
   getRoomEvents = (roomId: string) => {
     return this.testState.sdk!.getRoomEvents(roomId);
   };
+  getRoomIds = () => {
+    return this.testState.sdk!.serverState.rooms.map((r) => r.id);
+  };
   setRealmPermissions = (permissions: Record<string, string[]>) => {
     this.testState.opts!.realmPermissions = permissions;
     (this.testState.owner!.lookup('service:realm') as RealmService).logout();
diff --git a/packages/host/tests/integration/commands/switch-submode-test.gts b/packages/host/tests/integration/commands/switch-submode-test.gts
new file mode 100644
index 0000000000..d0dea2c9fe
--- /dev/null
+++ b/packages/host/tests/integration/commands/switch-submode-test.gts
@@ -0,0 +1,70 @@
+import { getOwner } from '@ember/owner';
+import { RenderingTestContext } from '@ember/test-helpers';
+
+import { module, test } from 'qunit';
+
+import { Loader } from '@cardstack/runtime-common';
+
+import type CommandService from '@cardstack/host/services/command-service';
+import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
+
+import RealmService from '@cardstack/host/services/realm';
+
+import type { SwitchSubmodeInput } from 'https://cardstack.com/base/command';
+
+import {
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+  lookupLoaderService,
+  lookupService,
+  testRealmURL,
+  testRealmInfo,
+} from '../../helpers';
+import { setupRenderingTest } from '../../helpers/setup';
+
+let loader: Loader;
+
+class StubRealmService extends RealmService {
+  get defaultReadableRealm() {
+    return {
+      path: testRealmURL,
+      info: testRealmInfo,
+    };
+  }
+}
+
+module('Integration | commands | switch-submode', function (hooks) {
+  setupRenderingTest(hooks);
+  setupLocalIndexing(hooks);
+
+  hooks.beforeEach(function (this: RenderingTestContext) {
+    getOwner(this)!.register('service:realm', StubRealmService);
+    loader = lookupLoaderService().loader;
+  });
+
+  hooks.beforeEach(async function () {
+    await setupIntegrationTestRealm({
+      loader,
+      contents: {},
+    });
+  });
+
+  test('switch to code submode', async function (assert) {
+    let commandService = lookupService<CommandService>('command-service');
+    let operatorModeStateService = lookupService<OperatorModeStateService>(
+      'operator-mode-state-service',
+    );
+    let switchSubmodeCommand = commandService.lookupCommand<
+      SwitchSubmodeInput,
+      undefined,
+      undefined
+    >('switch-submode', undefined);
+    const InputType = await switchSubmodeCommand.getInputType();
+    let input = new InputType({
+      submode: 'code',
+    });
+    assert.strictEqual(operatorModeStateService.state?.submode, 'interact');
+    await switchSubmodeCommand.execute(input);
+    assert.strictEqual(operatorModeStateService.state?.submode, 'code');
+  });
+});
diff --git a/packages/host/tests/integration/components/ai-assistant-panel-test.gts b/packages/host/tests/integration/components/ai-assistant-panel-test.gts
index c083c62bec..b5d1572d0a 100644
--- a/packages/host/tests/integration/components/ai-assistant-panel-test.gts
+++ b/packages/host/tests/integration/components/ai-assistant-panel-test.gts
@@ -390,8 +390,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: `${testRealmURL}Person/fadhlan`,
-            attributes: { firstName: 'Dave' },
+            attributes: {
+              cardId: `${testRealmURL}Person/fadhlan`,
+              patch: {
+                attributes: { firstName: 'Dave' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -458,8 +462,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: `${testRealmURL}Person/fadhlan`,
-            attributes: { firstName: 'Evie' },
+            attributes: {
+              cardId: `${testRealmURL}Person/fadhlan`,
+              patch: {
+                attributes: { firstName: 'Evie' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -479,8 +487,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: `${testRealmURL}Person/fadhlan`,
-            attributes: { firstName: 'Jackie' },
+            attributes: {
+              cardId: `${testRealmURL}Person/fadhlan`,
+              patch: {
+                attributes: { firstName: 'Jackie' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -542,82 +554,6 @@ module('Integration | ai-assistant-panel', function (hooks) {
       .exists();
   });
 
-  test('it only applies changes from the chat if the stack contains a card with that ID', async function (assert) {
-    let roomId = await renderAiAssistantPanel(`${testRealmURL}Person/fadhlan`);
-
-    await waitFor('[data-test-person]');
-    assert.dom('[data-test-boxel-card-header-title]').hasText('Person');
-    assert.dom('[data-test-person]').hasText('Fadhlan');
-
-    let otherCardID = `${testRealmURL}Person/burcu`;
-    await simulateRemoteMessage(roomId, '@aibot:localhost', {
-      body: 'i am the body',
-      msgtype: 'org.boxel.command',
-      formatted_body:
-        'A patch<pre><code>https://www.example.com/path/to/resource?query=param1value&anotherQueryParam=anotherValue&additionalParam=additionalValue&longparameter1=someLongValue1</code></pre>',
-      format: 'org.matrix.custom.html',
-      data: JSON.stringify({
-        toolCall: {
-          name: 'patchCard',
-          arguments: {
-            card_id: otherCardID,
-            attributes: { firstName: 'Dave' },
-          },
-        },
-        eventId: '__EVENT_ID__',
-      }),
-      'm.relates_to': {
-        rel_type: 'm.replace',
-        event_id: '__EVENT_ID__',
-      },
-    });
-
-    await waitFor('[data-test-command-apply="ready"]');
-    await click('[data-test-command-apply]');
-
-    await waitFor('[data-test-command-card-idle]');
-    assert
-      .dom('[data-test-card-error]')
-      .containsText(`Please open card '${otherCardID}' to make changes to it.`);
-    assert.dom('[data-test-apply-state="failed"]').exists();
-    assert.dom('[data-test-ai-bot-retry-button]').exists();
-    assert.dom('[data-test-command-apply]').doesNotExist();
-    assert.dom('[data-test-person]').hasText('Fadhlan');
-
-    await triggerEvent(
-      `[data-test-stack-card="${testRealmURL}Person/fadhlan"] [data-test-field-component-card][data-test-card-format="fitted"]`,
-      'mouseenter',
-    );
-    await waitFor('[data-test-overlay-card] [data-test-overlay-more-options]');
-    await percySnapshot(
-      'Integration | ai-assistant-panel | it only applies changes from the chat if the stack contains a card with that ID | error',
-    );
-
-    await setCardInOperatorModeState(otherCardID);
-    await waitFor('[data-test-person="Burcu"]');
-    click('[data-test-ai-bot-retry-button]'); // retry the command with correct card
-    await waitFor('[data-test-apply-state="applying"]');
-    assert.dom('[data-test-apply-state="applying"]').exists();
-
-    await waitFor('[data-test-command-card-idle]');
-    await waitFor('[data-test-apply-state="applied"]');
-    assert.dom('[data-test-apply-state="applied"]').exists();
-    assert.dom('[data-test-person]').hasText('Dave');
-    assert.dom('[data-test-command-apply]').doesNotExist();
-    assert.dom('[data-test-ai-bot-retry-button]').doesNotExist();
-
-    await triggerEvent(
-      `[data-test-stack-card="${testRealmURL}Person/burcu"] [data-test-plural-view="linksToMany"] [data-test-plural-view-item="0"]`,
-      'mouseenter',
-    );
-    assert
-      .dom('[data-test-overlay-card] [data-test-overlay-more-options]')
-      .exists();
-    await percySnapshot(
-      'Integration | ai-assistant-panel | it only applies changes from the chat if the stack contains a card with that ID | error fixed',
-    );
-  });
-
   test('it can apply change to nested contains field', async function (assert) {
     let roomId = await renderAiAssistantPanel(`${testRealmURL}Person/fadhlan`);
 
@@ -627,10 +563,14 @@ module('Integration | ai-assistant-panel', function (hooks) {
     let payload = {
       name: 'patchCard',
       arguments: {
-        card_id: `${testRealmURL}Person/fadhlan`,
         attributes: {
-          firstName: 'Joy',
-          address: { shippingInfo: { preferredCarrier: 'UPS' } },
+          cardId: `${testRealmURL}Person/fadhlan`,
+          patch: {
+            attributes: {
+              firstName: 'Joy',
+              address: { shippingInfo: { preferredCarrier: 'UPS' } },
+            },
+          },
         },
       },
       eventId: 'event1',
@@ -658,14 +598,18 @@ module('Integration | ai-assistant-panel', function (hooks) {
         name: 'patchCard',
         payload: {
           attributes: {
-            address: {
-              shippingInfo: {
-                preferredCarrier: 'UPS',
+            cardId: 'http://test-realm/test/Person/fadhlan',
+            patch: {
+              attributes: {
+                address: {
+                  shippingInfo: {
+                    preferredCarrier: 'UPS',
+                  },
+                },
+                firstName: 'Joy',
               },
             },
-            firstName: 'Joy',
           },
-          card_id: 'http://test-realm/test/Person/fadhlan',
         },
       },
       'it can preview code when a change is proposed',
@@ -698,12 +642,16 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
             attributes: {
-              address: { shippingInfo: { preferredCarrier: 'Fedex' } },
-            },
-            relationships: {
-              pet: { links: { self: null } },
+              cardId: id,
+              patch: {
+                attributes: {
+                  address: { shippingInfo: { preferredCarrier: 'Fedex' } },
+                },
+                relationships: {
+                  pet: { links: { self: null } },
+                },
+              },
             },
           },
         },
@@ -736,13 +684,17 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
             attributes: {
-              address: { shippingInfo: { preferredCarrier: 'UPS' } },
-            },
-            relationships: {
-              pet: {
-                links: { self: `${testRealmURL}Pet/mango` },
+              cardId: id,
+              patch: {
+                attributes: {
+                  address: { shippingInfo: { preferredCarrier: 'UPS' } },
+                },
+                relationships: {
+                  pet: {
+                    links: { self: `${testRealmURL}Pet/mango` },
+                  },
+                },
               },
             },
           },
@@ -785,8 +737,16 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
-            attributes: { trips: { tripTitle: 'Trip to Japan' } },
+            attributes: {
+              cardId: id,
+              patch: {
+                attributes: {
+                  trips: {
+                    tripTitle: 'Trip to Japan',
+                  },
+                },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -819,9 +779,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
-
-            attributes: { firstName: 'Dave' },
+            attributes: {
+              cardId: id,
+              patch: {
+                attributes: { firstName: 'Dave' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -862,8 +825,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
-            attributes: { firstName: 'Jackie' },
+            attributes: {
+              cardId: id,
+              patch: {
+                attributes: { firstName: 'Jackie' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -923,8 +890,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: id,
-            attributes: { firstName: 'Dave' },
+            attributes: {
+              cardId: id,
+              patch: {
+                attributes: { firstName: 'Dave' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -1198,7 +1169,6 @@ module('Integration | ai-assistant-panel', function (hooks) {
     assert.dom('[data-test-send-message-btn]').isDisabled();
     assert.dom('[data-test-ai-assistant-message]').exists({ count: 1 });
     assert.dom('[data-test-ai-assistant-message]').hasClass('is-pending');
-
     await waitFor('[data-test-ai-assistant-message].is-error');
     await waitUntil(
       () =>
@@ -1231,8 +1201,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: `${testRealmURL}Person/fadhlan`,
-            attributes: { firstName: 'Dave' },
+            attributes: {
+              cardId: `${testRealmURL}Person/fadhlan`,
+              patch: {
+                attributes: { firstName: 'Dave' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -1892,8 +1866,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'patchCard',
           arguments: {
-            card_id: `${testRealmURL}Person/fadhlan`,
-            attributes: { firstName: 'Evie' },
+            attributes: {
+              cardId: `${testRealmURL}Person/fadhlan`,
+              patch: {
+                attributes: { firstName: 'Evie' },
+              },
+            },
           },
         },
         eventId: '__EVENT_ID__',
@@ -1961,11 +1939,13 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'searchCard',
           arguments: {
-            description: 'Searching for card',
-            filter: {
-              type: {
-                module: `${testRealmURL}pet`,
-                name: 'Pet',
+            attributes: {
+              description: 'Searching for card',
+              filter: {
+                type: {
+                  module: `${testRealmURL}pet`,
+                  name: 'Pet',
+                },
               },
             },
           },
@@ -2025,11 +2005,13 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'searchCard',
           arguments: {
-            description: 'Searching for card',
-            filter: {
-              type: {
-                module: `${testRealmURL}pet`,
-                name: 'Pet',
+            attributes: {
+              description: 'Searching for card',
+              filter: {
+                type: {
+                  module: `${testRealmURL}pet`,
+                  name: 'Pet',
+                },
               },
             },
           },
@@ -2084,10 +2066,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'searchCard',
           arguments: {
-            description: 'Searching for card',
-            filter: {
-              contains: {
-                title: 'Mango',
+            attributes: {
+              description: 'Searching for card',
+              filter: {
+                contains: {
+                  title: 'Mango',
+                },
               },
             },
           },
@@ -2140,11 +2124,13 @@ module('Integration | ai-assistant-panel', function (hooks) {
         toolCall: {
           name: 'searchCard',
           arguments: {
-            description: 'Searching for card',
-            filter: {
-              type: {
-                module: `${testRealmURL}person`,
-                name: 'Person',
+            attributes: {
+              description: 'Searching for card',
+              filter: {
+                type: {
+                  module: `${testRealmURL}person`,
+                  name: 'Person',
+                },
               },
             },
           },
@@ -2190,10 +2176,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
     const roomId = await renderAiAssistantPanel(id);
     const toolArgs = {
       description: 'Search for Person cards',
-      filter: {
-        type: {
-          module: `${testRealmURL}person`,
-          name: 'Person',
+      attributes: {
+        filter: {
+          type: {
+            module: `${testRealmURL}person`,
+            name: 'Person',
+          },
         },
       },
     };
@@ -2249,7 +2237,7 @@ module('Integration | ai-assistant-panel', function (hooks) {
       .hasText(`Description ${toolArgs.description}`);
     assert
       .dom(`${savedCard} [data-test-boxel-field]:nth-child(2)`)
-      .hasText(`Filter ${JSON.stringify(toolArgs.filter, null, 2)}`);
+      .hasText(`Filter ${JSON.stringify(toolArgs.attributes.filter, null, 2)}`);
 
     resultListItem = `${savedCard} ${resultListItem}`;
     assert.dom(resultListItem).exists({ count: 8 });
@@ -2263,10 +2251,12 @@ module('Integration | ai-assistant-panel', function (hooks) {
     const roomId = await renderAiAssistantPanel(id);
     const toolArgs = {
       description: 'Search for Person cards',
-      filter: {
-        type: {
-          module: `${testRealmURL}person`,
-          name: 'Person',
+      attributes: {
+        filter: {
+          type: {
+            module: `${testRealmURL}person`,
+            name: 'Person',
+          },
         },
       },
     };
@@ -2324,7 +2314,7 @@ module('Integration | ai-assistant-panel', function (hooks) {
       .hasText(`Description ${toolArgs.description}`);
     assert
       .dom(`${savedCard} [data-test-boxel-field]:nth-child(2)`)
-      .hasText(`Filter ${JSON.stringify(toolArgs.filter, null, 2)}`);
+      .hasText(`Filter ${JSON.stringify(toolArgs.attributes.filter, null, 2)}`);
 
     resultListItem = `${savedCard} ${resultListItem}`;
     assert.dom(resultListItem).exists({ count: 8 });
diff --git a/packages/host/tests/integration/components/prerendered-card-search-test.gts b/packages/host/tests/integration/components/prerendered-card-search-test.gts
index 6cd2dbe27f..12afdf206e 100644
--- a/packages/host/tests/integration/components/prerendered-card-search-test.gts
+++ b/packages/host/tests/integration/components/prerendered-card-search-test.gts
@@ -402,7 +402,6 @@ module(`Integration | prerendered-card-search`, function (hooks) {
       callback: async () => {
         let owner = (getContext() as TestContext).owner;
         let cardService = owner.lookup('service:card-service') as CardService;
-        console.log('triggering card deletion');
         await cardService.deleteSource(new URL(`${testRealmURL}card-2.json`));
       },
     });
diff --git a/packages/host/tests/integration/resources/search-test.ts b/packages/host/tests/integration/resources/search-test.ts
index da11b8b8e0..5cb8a4a5b4 100644
--- a/packages/host/tests/integration/resources/search-test.ts
+++ b/packages/host/tests/integration/resources/search-test.ts
@@ -276,7 +276,6 @@ module(`Integration | search resource`, function (hooks) {
       },
     })) as Search;
     await search.loaded;
-    console.log(search.instances[0]);
     assert.strictEqual(search.instances[0].id, `${testRealmURL}card-2`);
     assert.strictEqual(search.instances[0].constructor.name, 'Book');
   });
diff --git a/packages/host/tests/unit/ai-function-generation-test.ts b/packages/host/tests/unit/ai-function-generation-test.ts
index 3125345128..dd0a1fbc98 100644
--- a/packages/host/tests/unit/ai-function-generation-test.ts
+++ b/packages/host/tests/unit/ai-function-generation-test.ts
@@ -4,7 +4,7 @@ import { module, test } from 'qunit';
 
 import { baseRealm } from '@cardstack/runtime-common';
 import {
-  generateCardPatchCallSpecification,
+  generateJsonSchemaForCardType,
   basicMappings,
   type LinksToSchema,
   type RelationshipSchema,
@@ -78,11 +78,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field bigIntegerField = contains(BigIntegerField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      BasicCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(BasicCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -98,6 +94,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           bigIntegerField: { type: 'string', pattern: '^-?[0-9]+$' },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -117,11 +117,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field containerField = contains(InternalField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      BasicCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(BasicCard, cardApi, mappings);
     const links: LinksToSchema['properties']['links'] = {
       type: 'object',
       properties: {
@@ -177,11 +173,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field containerField = contains(InternalField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -197,6 +189,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -214,11 +210,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field linkedCard2 = linksTo(OtherCard);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
 
     let attributes: ObjectSchema = {
       type: 'object',
@@ -265,11 +257,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field linkedCards = linksToMany(OtherCard);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
 
     let attributes: ObjectSchema = {
       type: 'object',
@@ -326,11 +314,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field child = contains(ChildField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      ParentCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(ParentCard, cardApi, mappings);
 
     let attributes: ObjectSchema = {
       type: 'object',
@@ -399,11 +383,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field traveler = contains(Traveler);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TripInfo,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TripInfo, cardApi, mappings);
     const links: LinksToSchema['properties']['links'] = {
       type: 'object',
       properties: {
@@ -478,11 +458,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field skipField = contains(NewField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -493,6 +469,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           keepField: { type: 'string' },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -509,11 +489,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field keepField = contains(NewField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -524,6 +500,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           keepField: { type: 'string' },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -544,11 +524,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field containingField = contains(ContainingField);
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
 
     assert.deepEqual(schema, {
       attributes: {
@@ -565,6 +541,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -581,11 +561,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       });
     }
 
-    let schema = generateCardPatchCallSpecification(
-      BasicCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(BasicCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -602,6 +578,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 
@@ -630,11 +610,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       });
     }
 
-    let schema = generateCardPatchCallSpecification(
-      BasicCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(BasicCard, cardApi, mappings);
     const links: LinksToSchema['properties']['links'] = {
       type: 'object',
       properties: {
@@ -714,11 +690,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       @field linkedCard2 = linksTo(OtherCard, { description: 'linked card' });
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
 
     let attributes: ObjectSchema = {
       type: 'object',
@@ -780,11 +752,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       });
     }
 
-    let schema = generateCardPatchCallSpecification(
-      TestCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(TestCard, cardApi, mappings);
 
     let attributes: ObjectSchema = {
       type: 'object',
@@ -834,11 +802,7 @@ module('Unit | ai-function-generation-test', function (hooks) {
       });
     }
 
-    let schema = generateCardPatchCallSpecification(
-      BasicCard,
-      cardApi,
-      mappings,
-    );
+    let schema = generateJsonSchemaForCardType(BasicCard, cardApi, mappings);
     assert.deepEqual(schema, {
       attributes: {
         type: 'object',
@@ -858,6 +822,10 @@ module('Unit | ai-function-generation-test', function (hooks) {
           },
         },
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+      },
     });
   });
 });
diff --git a/packages/matrix/helpers/index.ts b/packages/matrix/helpers/index.ts
index e005900647..3cb9c83a96 100644
--- a/packages/matrix/helpers/index.ts
+++ b/packages/matrix/helpers/index.ts
@@ -607,13 +607,15 @@ export async function getRoomEvents(
     );
     // there will generally be 2 rooms, one is the DM room we do for
     // authentication, the other is the actual chat (with org.boxel.message events)
-    return roomsWithEvents.find((messages) => {
-      return messages.find(
-        (message) =>
-          message.type === 'm.room.message' &&
-          message.content?.msgtype === 'org.boxel.message',
-      );
-    })!;
+    return (
+      roomsWithEvents.find((messages) => {
+        return messages.find(
+          (message) =>
+            message.type === 'm.room.message' &&
+            message.content?.msgtype === 'org.boxel.message',
+        );
+      }) ?? []
+    );
   }
   return await getAllRoomEvents(roomId, accessToken);
 }
@@ -623,3 +625,19 @@ export async function getRoomsFromSync(username = 'user1', password = 'pass') {
   let response = (await sync(accessToken)) as any;
   return response.rooms;
 }
+
+export async function waitUntil<T>(
+  condition: () => Promise<T>,
+  timeout = 10000,
+  interval = 250,
+): Promise<T> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    const result = await condition();
+    if (result) {
+      return result;
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+  throw new Error('Timeout waiting for condition');
+}
diff --git a/packages/matrix/tests/commands.spec.ts b/packages/matrix/tests/commands.spec.ts
new file mode 100644
index 0000000000..152385d244
--- /dev/null
+++ b/packages/matrix/tests/commands.spec.ts
@@ -0,0 +1,392 @@
+import { expect, test } from '@playwright/test';
+import { Credentials, putEvent, registerUser } from '../docker/synapse';
+
+import {
+  login,
+  getRoomId,
+  sendMessage,
+  testHost,
+  registerRealmUsers,
+  getRoomEvents,
+  showAllCards,
+  waitUntil,
+} from '../helpers';
+import {
+  synapseStart,
+  synapseStop,
+  type SynapseInstance,
+} from '../docker/synapse';
+
+test.describe('Commands', () => {
+  let synapse: SynapseInstance;
+  let userCred: Credentials;
+  test.beforeEach(async () => {
+    synapse = await synapseStart();
+    await registerRealmUsers(synapse);
+    userCred = await registerUser(synapse, 'user1', 'pass');
+  });
+  test.afterEach(async () => {
+    await synapseStop(synapse.synapseId);
+  });
+
+  test(`it does include command tools (patch, search, generateAppModule) in message event when top-most card is writable and context is shared`, async ({
+    page,
+  }) => {
+    await login(page, 'user1', 'pass');
+    let room1 = await getRoomId(page);
+    await showAllCards(page);
+    await page
+      .locator(
+        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${testHost}/mango"]`,
+      )
+      .click();
+    await expect(
+      page.locator(`[data-test-stack-card="${testHost}/mango"]`),
+    ).toHaveCount(1);
+    await sendMessage(page, room1, 'please change this card');
+    let message = (await getRoomEvents()).pop()!;
+    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
+    let boxelMessageData = JSON.parse(message.content.data);
+
+    expect(boxelMessageData.context.tools.length).toEqual(3);
+    let patchCardTool = boxelMessageData.context.tools.find(
+      (t: any) => t.function.name === 'patchCard',
+    );
+    expect(patchCardTool).toMatchObject({
+      type: 'function',
+      function: {
+        name: 'patchCard',
+        description:
+          'Propose a patch to an existing card to change its contents. Any attributes specified will be fully replaced, return the minimum required to make the change. If a relationship field value is removed, set the self property of the specific item to null. When editing a relationship array, display the full array in the patch code. Ensure the description explains what change you are making.',
+        parameters: {
+          type: 'object',
+          properties: {
+            attributes: {
+              type: 'object',
+              properties: {
+                cardId: {
+                  type: 'string',
+                  const: `${testHost}/mango`,
+                },
+                patch: {
+                  type: 'object',
+                  properties: {
+                    attributes: {
+                      type: 'object',
+                      properties: {
+                        firstName: {
+                          type: 'string',
+                        },
+                        lastName: {
+                          type: 'string',
+                        },
+                        email: {
+                          type: 'string',
+                        },
+                        posts: {
+                          type: 'number',
+                        },
+                        thumbnailURL: {
+                          type: 'string',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          required: ['attributes', 'description'],
+        },
+      },
+    });
+    let searchCardTool = boxelMessageData.context.tools.find(
+      (t: any) => t.function.name === 'searchCard',
+    );
+    expect(searchCardTool).toMatchObject({
+      type: 'function',
+      function: {
+        name: 'searchCard',
+        description:
+          'Propose a query to search for a card instance filtered by type.   If a card was shared with you, always prioritise search based upon the card that was last shared.   If you do not have information on card module and name, do the search using the `_cardType` attribute.',
+        parameters: {
+          type: 'object',
+          properties: {
+            description: {
+              type: 'string',
+            },
+            attributes: {
+              type: 'object',
+              properties: {
+                filter: {
+                  type: 'object',
+                  properties: {
+                    contains: {
+                      type: 'object',
+                      properties: {
+                        title: {
+                          type: 'string',
+                          description: 'title of the card',
+                        },
+                      },
+                      required: ['title'],
+                    },
+                    eq: {
+                      type: 'object',
+                      properties: {
+                        _cardType: {
+                          type: 'string',
+                          description: 'name of the card type',
+                        },
+                      },
+                      required: ['_cardType'],
+                    },
+                  },
+                },
+              },
+            },
+          },
+          required: ['attributes', 'description'],
+        },
+      },
+    });
+    let generateAppModuleTool = boxelMessageData.context.tools.find(
+      (t: any) => t.function.name === 'generateAppModule',
+    );
+    expect(generateAppModuleTool).toMatchObject({
+      type: 'function',
+      function: {
+        name: 'generateAppModule',
+        description: `Propose a post request to generate a new app module. Insert the module code in the 'moduleCode' property of the payload and the title for the module in the 'appTitle' property. Ensure the description explains what change you are making.`,
+        parameters: {
+          type: 'object',
+          properties: {
+            attached_card_id: {
+              type: 'string',
+              const: `${testHost}/mango`,
+            },
+            description: {
+              type: 'string',
+            },
+            appTitle: {
+              type: 'string',
+            },
+            moduleCode: {
+              type: 'string',
+            },
+          },
+          required: [
+            'attached_card_id',
+            'description',
+            'appTitle',
+            'moduleCode',
+          ],
+        },
+      },
+    });
+  });
+
+  test(`it does not include patch tool in message event for an open card that is not attached`, async ({
+    page,
+  }) => {
+    await login(page, 'user1', 'pass');
+    let room1 = await getRoomId(page);
+    await showAllCards(page);
+    await page
+      .locator(
+        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${testHost}/mango"]`,
+      )
+      .click();
+    await expect(
+      page.locator(`[data-test-stack-card="${testHost}/mango"]`),
+    ).toHaveCount(1);
+    await page
+      .locator(
+        `[data-test-attached-card="${testHost}/mango"] [data-test-remove-card-btn]`,
+      )
+      .click();
+    await sendMessage(page, room1, 'please change this card');
+    let message = (await getRoomEvents()).pop()!;
+    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
+    let boxelMessageData = JSON.parse(message.content.data);
+    expect(boxelMessageData.context.tools).toMatchObject([]);
+  });
+
+  test(`it does not include patch tool in message event when top-most card is read-only`, async ({
+    page,
+  }) => {
+    // the base realm is a read-only realm
+    await login(page, 'user1', 'pass', { url: `http://localhost:4201/base` });
+    let room1 = await getRoomId(page);
+    await showAllCards(page);
+    await expect(
+      page.locator(
+        '[data-test-stack-card="https://cardstack.com/base/index"] [data-test-cards-grid-item="https://cardstack.com/base/fields/boolean-field"]',
+      ),
+    ).toHaveCount(1);
+    await page
+      .locator(
+        '[data-test-stack-card="https://cardstack.com/base/index"] [data-test-cards-grid-item="https://cardstack.com/base/fields/boolean-field"]',
+      )
+      .click();
+    await expect(
+      page.locator(
+        '[data-test-stack-card="https://cardstack.com/base/fields/boolean-field"]',
+      ),
+    ).toHaveCount(1);
+    await sendMessage(page, room1, 'please change this card');
+    let message = (await getRoomEvents()).pop()!;
+    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
+    let boxelMessageData = JSON.parse(message.content.data);
+    expect(boxelMessageData.context.tools).toMatchObject([]);
+  });
+
+  test(`applying a command dispatches a reaction event if command is succesful`, async ({
+    page,
+  }) => {
+    await login(page, 'user1', 'pass');
+    let room1 = await getRoomId(page);
+    let cardId = `${testHost}/hassan`;
+    let content = {
+      msgtype: 'org.boxel.command',
+      format: 'org.matrix.custom.html',
+      body: 'some command',
+      formatted_body: 'some command',
+      data: JSON.stringify({
+        toolCall: {
+          name: 'patchCard',
+          arguments: {
+            attributes: {
+              cardId,
+              description: 'Patching card',
+              patch: {
+                attributes: {
+                  firstName: 'Dave',
+                },
+              },
+            },
+          },
+        },
+      }),
+    };
+
+    await showAllCards(page);
+    await page
+      .locator(
+        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${cardId}"]`,
+      )
+      .click();
+    await putEvent(userCred.accessToken, room1, 'm.room.message', '1', content);
+    await page.locator('[data-test-command-apply]').click();
+    await page.locator('[data-test-command-idle]');
+
+    await expect(async () => {
+      let events = await getRoomEvents('user1', 'pass', room1);
+      let reactionEvent = (events as any).find(
+        (e: any) => e.type === 'm.reaction',
+      );
+      await expect(reactionEvent).toBeDefined();
+    }).toPass();
+  });
+
+  test(`applying a search command dispatches a result event if command is succesful and result is returned`, async ({
+    page,
+  }) => {
+    await login(page, 'user1', 'pass');
+    let room1 = await getRoomId(page);
+    let card_id = `${testHost}/hassan`;
+    let content = {
+      msgtype: 'org.boxel.command',
+      format: 'org.matrix.custom.html',
+      body: 'some command',
+      formatted_body: 'some command',
+      data: JSON.stringify({
+        toolCall: {
+          name: 'searchCard',
+          arguments: {
+            attributes: {
+              description: 'Searching for card',
+              filter: {
+                type: {
+                  module: `${testHost}person`,
+                  name: 'Person',
+                },
+              },
+            },
+          },
+        },
+        eventId: 'search1',
+      }),
+    };
+
+    await showAllCards(page);
+    await page
+      .locator(
+        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${card_id}"]`,
+      )
+      .click();
+    await putEvent(userCred.accessToken, room1, 'm.room.message', '1', content);
+    await page.locator('[data-test-command-apply]').click();
+    await page.locator('[data-test-command-idle]');
+    await expect(async () => {
+      let events = await getRoomEvents('user1', 'pass', room1);
+      let commandResultEvent = (events as any).find(
+        (e: any) => e.content.msgtype === 'org.boxel.commandResult',
+      );
+      await expect(commandResultEvent).toBeDefined();
+    }).toPass();
+  });
+
+  test('a command sent via sendAiAssistantMessage becomes an available tool', async ({
+    page,
+  }) => {
+    await login(page, 'user1', 'pass');
+    await showAllCards(page);
+    await page
+      .locator(
+        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${testHost}/mango"]`,
+      )
+      .click();
+    await expect(
+      page.locator(`[data-test-stack-card="${testHost}/mango"]`),
+    ).toHaveCount(1);
+    await page.locator('[data-test-switch-to-code-mode-button]').click();
+    await waitUntil(async () => (await getRoomEvents()).length > 0);
+    let message = (await getRoomEvents()).pop()!;
+    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
+    let boxelMessageData = JSON.parse(message.content.data);
+    expect(boxelMessageData.context.tools.length).toEqual(1);
+    expect(boxelMessageData.context.tools[0].type).toEqual('function');
+    expect(boxelMessageData.context.tools[0].function.name).toMatch(
+      /^SwitchSubmodeCommand_/,
+    );
+    expect(boxelMessageData.context.tools[0].function.description).toEqual(
+      'Navigate the UI to another submode. Possible values for submode are "interact" and "code".',
+    );
+    // TODO: do we need to include `required: ['attributes'],` in the parameters object? If so, how?
+    expect(boxelMessageData.context.tools[0].function.parameters).toMatchObject(
+      {
+        type: 'object',
+        properties: {
+          attributes: {
+            type: 'object',
+            properties: {
+              submode: {
+                type: 'string',
+              },
+              title: {
+                type: 'string',
+              },
+              description: {
+                type: 'string',
+              },
+              thumbnailURL: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    );
+  });
+});
diff --git a/packages/matrix/tests/messages.spec.ts b/packages/matrix/tests/messages.spec.ts
index dce67d07a9..acb959a008 100644
--- a/packages/matrix/tests/messages.spec.ts
+++ b/packages/matrix/tests/messages.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { Credentials, putEvent, registerUser } from '../docker/synapse';
+import { registerUser } from '../docker/synapse';
 import {
   login,
   logout,
@@ -26,11 +26,10 @@ import {
 
 test.describe('Room messages', () => {
   let synapse: SynapseInstance;
-  let userCred: Credentials;
   test.beforeEach(async () => {
     synapse = await synapseStart();
     await registerRealmUsers(synapse);
-    userCred = await registerUser(synapse, 'user1', 'pass');
+    await registerUser(synapse, 'user1', 'pass');
   });
   test.afterEach(async () => {
     await synapseStop(synapse.synapseId);
@@ -292,198 +291,6 @@ test.describe('Room messages', () => {
     expect(serializeCard.data.attributes.picture).toBeUndefined();
   });
 
-  test(`it does include command tools (patch, search, generateAppModule) in message event when top-most card is writable and context is shared`, async ({
-    page,
-  }) => {
-    await login(page, 'user1', 'pass');
-    let room1 = await getRoomId(page);
-    await showAllCards(page);
-    await page
-      .locator(
-        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${testHost}/mango"]`,
-      )
-      .click();
-    await expect(
-      page.locator(`[data-test-stack-card="${testHost}/mango"]`),
-    ).toHaveCount(1);
-    await sendMessage(page, room1, 'please change this card');
-    let message = (await getRoomEvents()).pop()!;
-    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
-    let boxelMessageData = JSON.parse(message.content.data);
-
-    expect(boxelMessageData.context.tools).toMatchObject([
-      {
-        type: 'function',
-        function: {
-          name: 'patchCard',
-          description:
-            'Propose a patch to an existing card to change its contents. Any attributes specified will be fully replaced, return the minimum required to make the change. If a relationship field value is removed, set the self property of the specific item to null. When editing a relationship array, display the full array in the patch code. Ensure the description explains what change you are making.',
-          parameters: {
-            type: 'object',
-            properties: {
-              description: {
-                type: 'string',
-              },
-              card_id: {
-                type: 'string',
-                const: `${testHost}/mango`,
-              },
-              attributes: {
-                type: 'object',
-                properties: {
-                  firstName: {
-                    type: 'string',
-                  },
-                  lastName: {
-                    type: 'string',
-                  },
-                  email: {
-                    type: 'string',
-                  },
-                  posts: {
-                    type: 'number',
-                  },
-                  thumbnailURL: {
-                    type: 'string',
-                  },
-                },
-              },
-            },
-            required: ['card_id', 'attributes', 'description'],
-          },
-        },
-      },
-      {
-        type: 'function',
-        function: {
-          name: 'searchCard',
-          description:
-            'Propose a query to search for a card instance filtered by type.   If a card was shared with you, always prioritise search based upon the card that was last shared.   If you do not have information on card module and name, do the search using the `_cardType` attribute.',
-          parameters: {
-            type: 'object',
-            properties: {
-              description: {
-                type: 'string',
-              },
-              filter: {
-                type: 'object',
-                properties: {
-                  contains: {
-                    type: 'object',
-                    properties: {
-                      title: {
-                        type: 'string',
-                        description: 'title of the card',
-                      },
-                    },
-                    required: ['title'],
-                  },
-                  eq: {
-                    type: 'object',
-                    properties: {
-                      _cardType: {
-                        type: 'string',
-                        description: 'name of the card type',
-                      },
-                    },
-                    required: ['_cardType'],
-                  },
-                },
-              },
-            },
-            required: ['filter', 'description'],
-          },
-        },
-      },
-      {
-        type: 'function',
-        function: {
-          name: 'generateAppModule',
-          description: `Propose a post request to generate a new app module. Insert the module code in the 'moduleCode' property of the payload and the title for the module in the 'appTitle' property. Ensure the description explains what change you are making.`,
-          parameters: {
-            type: 'object',
-            properties: {
-              attached_card_id: {
-                type: 'string',
-                const: `${testHost}/mango`,
-              },
-              description: {
-                type: 'string',
-              },
-              appTitle: {
-                type: 'string',
-              },
-              moduleCode: {
-                type: 'string',
-              },
-            },
-            required: [
-              'attached_card_id',
-              'description',
-              'appTitle',
-              'moduleCode',
-            ],
-          },
-        },
-      },
-    ]);
-  });
-
-  test(`it does not include patch tool in message event for an open card that is not attached`, async ({
-    page,
-  }) => {
-    await login(page, 'user1', 'pass');
-    let room1 = await getRoomId(page);
-    await showAllCards(page);
-    await page
-      .locator(
-        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${testHost}/mango"]`,
-      )
-      .click();
-    await expect(
-      page.locator(`[data-test-stack-card="${testHost}/mango"]`),
-    ).toHaveCount(1);
-    await page
-      .locator(
-        `[data-test-attached-card="${testHost}/mango"] [data-test-remove-card-btn]`,
-      )
-      .click();
-    await sendMessage(page, room1, 'please change this card');
-    let message = (await getRoomEvents()).pop()!;
-    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
-    let boxelMessageData = JSON.parse(message.content.data);
-    expect(boxelMessageData.context.tools).toMatchObject([]);
-  });
-
-  test(`it does not include patch tool in message event when top-most card is read-only`, async ({
-    page,
-  }) => {
-    // the base realm is a read-only realm
-    await login(page, 'user1', 'pass', { url: `http://localhost:4201/base` });
-    let room1 = await getRoomId(page);
-    await showAllCards(page);
-    await expect(
-      page.locator(
-        '[data-test-stack-card="https://cardstack.com/base/index"] [data-test-cards-grid-item="https://cardstack.com/base/fields/boolean-field"]',
-      ),
-    ).toHaveCount(1);
-    await page
-      .locator(
-        '[data-test-stack-card="https://cardstack.com/base/index"] [data-test-cards-grid-item="https://cardstack.com/base/fields/boolean-field"]',
-      )
-      .click();
-    await expect(
-      page.locator(
-        '[data-test-stack-card="https://cardstack.com/base/fields/boolean-field"]',
-      ),
-    ).toHaveCount(1);
-    await sendMessage(page, room1, 'please change this card');
-    let message = (await getRoomEvents()).pop()!;
-    expect(message.content.msgtype).toStrictEqual('org.boxel.message');
-    let boxelMessageData = JSON.parse(message.content.data);
-    expect(boxelMessageData.context.tools).toMatchObject([]);
-  });
-
   test('can send only a card as a message', async ({ page }) => {
     const testCard = `${testHost}/hassan`;
     await login(page, 'user1', 'pass');
@@ -1127,93 +934,4 @@ test.describe('Room messages', () => {
       0,
     );
   });
-
-  test(`applying a command dispatches a reaction event if command is succesful`, async ({
-    page,
-  }) => {
-    await login(page, 'user1', 'pass');
-    let room1 = await getRoomId(page);
-    let card_id = `${testHost}/hassan`;
-    let content = {
-      msgtype: 'org.boxel.command',
-      format: 'org.matrix.custom.html',
-      body: 'some command',
-      formatted_body: 'some command',
-      data: JSON.stringify({
-        toolCall: {
-          name: 'patchCard',
-          arguments: {
-            card_id,
-            attributes: {
-              firstName: 'Dave',
-            },
-          },
-        },
-      }),
-    };
-
-    await showAllCards(page);
-    await page
-      .locator(
-        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${card_id}"]`,
-      )
-      .click();
-    await putEvent(userCred.accessToken, room1, 'm.room.message', '1', content);
-    await page.locator('[data-test-command-apply]').click();
-    await page.locator('[data-test-command-idle]');
-
-    await expect(async () => {
-      let events = await getRoomEvents('user1', 'pass', room1);
-      let reactionEvent = (events as any).find(
-        (e: any) => e.type === 'm.reaction',
-      );
-      await expect(reactionEvent).toBeDefined();
-    }).toPass();
-  });
-
-  test(`applying a search command dispatches a result event if command is succesful and result is returned`, async ({
-    page,
-  }) => {
-    await login(page, 'user1', 'pass');
-    let room1 = await getRoomId(page);
-    let card_id = `${testHost}/hassan`;
-    let content = {
-      msgtype: 'org.boxel.command',
-      format: 'org.matrix.custom.html',
-      body: 'some command',
-      formatted_body: 'some command',
-      data: JSON.stringify({
-        toolCall: {
-          name: 'searchCard',
-          arguments: {
-            description: 'Searching for card',
-            filter: {
-              type: {
-                module: `${testHost}person`,
-                name: 'Person',
-              },
-            },
-          },
-        },
-        eventId: 'search1',
-      }),
-    };
-
-    await showAllCards(page);
-    await page
-      .locator(
-        `[data-test-stack-card="${testHost}/index"] [data-test-cards-grid-item="${card_id}"]`,
-      )
-      .click();
-    await putEvent(userCred.accessToken, room1, 'm.room.message', '1', content);
-    await page.locator('[data-test-command-apply]').click();
-    await page.locator('[data-test-command-idle]');
-    await expect(async () => {
-      let events = await getRoomEvents('user1', 'pass', room1);
-      let commandResultEvent = (events as any).find(
-        (e: any) => e.content.msgtype === 'org.boxel.commandResult',
-      );
-      await expect(commandResultEvent).toBeDefined();
-    }).toPass();
-  });
 });
diff --git a/packages/runtime-common/commands.ts b/packages/runtime-common/commands.ts
new file mode 100644
index 0000000000..6acf15dc7b
--- /dev/null
+++ b/packages/runtime-common/commands.ts
@@ -0,0 +1,119 @@
+import { Deferred } from './deferred';
+import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import { CardDef } from 'https://cardstack.com/base/card-api';
+import { SkillCard } from 'https://cardstack.com/base/skill-card';
+import {
+  AttributesSchema,
+  CardSchema,
+  generateJsonSchemaForCardType,
+} from './helpers/ai';
+
+export interface CommandContext {
+  lookupCommand<
+    CardInputType extends CardDef | undefined,
+    CardResultType extends CardDef | undefined,
+    CommandConfiguration extends any | undefined = undefined,
+  >(
+    name: string,
+    commandConfiguration?: CommandConfiguration,
+  ): Command<CardInputType, CardResultType, CommandConfiguration>;
+
+  sendAiAssistantMessage: (params: {
+    roomId?: string; // if falsy we create a new room
+    show?: boolean; // if truthy, ensure the side panel to the room
+    prompt: string;
+    attachedCards?: CardDef[];
+    skillCards?: SkillCard[];
+    commands?: { command: Command<any, any, any>; autoExecute: boolean }[];
+  }) => Promise<{ roomId: string }>;
+}
+
+export class CommandInvocation<
+  CardInputType extends CardDef | undefined,
+  CardResultType extends CardDef | undefined,
+> {
+  result?: CardResultType;
+  error: Error | undefined;
+  status: 'pending' | 'success' | 'error' = 'pending';
+  private deferred: Deferred<CardResultType> = new Deferred<CardResultType>();
+
+  constructor(public readonly input: CardInputType) {}
+
+  get promise(): Promise<CardResultType> {
+    return this.deferred.promise;
+  }
+
+  fulfill(result: CardResultType): void {
+    this.status = 'success';
+    this.deferred.fulfill(result);
+  }
+
+  reject(error: unknown): void {
+    this.status = 'error';
+    this.deferred.reject(error);
+  }
+}
+
+export abstract class Command<
+  CardInputType extends CardDef | undefined,
+  CardResultType extends CardDef | undefined,
+  CommandConfiguration extends any | undefined = undefined,
+> {
+  // Is this actually type checking ?
+  abstract getInputType(): Promise<{ new (args: any): CardInputType }>; // TODO: can we do better than any here?
+
+  invocations: CommandInvocation<CardInputType, CardResultType>[] = [];
+
+  nextCompletionDeferred: Deferred<CardResultType> =
+    new Deferred<CardResultType>();
+
+  name: string = this.constructor.name;
+  description = '';
+
+  constructor(
+    protected readonly commandContext: CommandContext,
+    protected readonly configuration: CommandConfiguration, // we'd like this to be required *if* CommandConfiguration is defined, and allow the user to skip it when CommandConfiguration is undefined
+  ) {}
+
+  async execute(input: CardInputType): Promise<CardResultType> {
+    // internal bookkeeping
+    // todo: support for this.runTask being defined
+    // runTask would be an ember task, run would just be a normal function
+
+    let invocation = new CommandInvocation<CardInputType, CardResultType>(
+      input,
+    );
+
+    this.invocations.push(invocation);
+    this.nextCompletionDeferred.fulfill(invocation.promise);
+
+    try {
+      let result = await this.run(input);
+      invocation.fulfill(result);
+      return result;
+    } catch (error) {
+      invocation.reject(error);
+      throw error;
+    } finally {
+      this.nextCompletionDeferred = new Deferred<CardResultType>();
+    }
+  }
+
+  protected abstract run(input: CardInputType): Promise<CardResultType>;
+
+  waitForNextCompletion(): Promise<CardResultType> {
+    return this.nextCompletionDeferred.promise;
+  }
+
+  async getInputJsonSchema(
+    cardApi: typeof CardAPI,
+    mappings: Map<typeof CardAPI.FieldDef, AttributesSchema>,
+  ): Promise<CardSchema> {
+    let InputType = await this.getInputType();
+    return generateJsonSchemaForCardType(
+      InputType as unknown as typeof CardDef, // TODO: can we do better type-wise?
+      cardApi,
+      mappings,
+    );
+  }
+}
diff --git a/packages/runtime-common/helpers/ai.ts b/packages/runtime-common/helpers/ai.ts
index 8ed51e9d3a..4812432b8b 100644
--- a/packages/runtime-common/helpers/ai.ts
+++ b/packages/runtime-common/helpers/ai.ts
@@ -7,7 +7,7 @@ import type { Tool } from 'https://cardstack.com/base/matrix-event';
 type ArraySchema = {
   type: 'array';
   description?: string;
-  items: Schema;
+  items: AttributesSchema;
   minItems?: number;
   maxItems?: number;
   uniqueItems?: boolean;
@@ -17,7 +17,7 @@ export type ObjectSchema = {
   type: 'object';
   description?: string;
   properties: {
-    [fieldName: string]: Schema;
+    [fieldName: string]: AttributesSchema;
   };
   required?: string[];
 };
@@ -51,7 +51,7 @@ export type RelationshipsSchema = {
   properties: {
     [fieldName: string]: LinksToSchema | LinksToManySchema;
   };
-  required: string[]; // fieldName array;
+  required?: string[]; // fieldName array;
 };
 
 type DateSchema = {
@@ -90,7 +90,7 @@ type EnumSchema = {
   enum: any[];
 };
 
-export type Schema =
+export type AttributesSchema =
   | ArraySchema
   | ObjectSchema
   | DateSchema
@@ -99,12 +99,17 @@ export type Schema =
   | EnumSchema
   | BooleanSchema;
 
+export interface CardSchema {
+  attributes: AttributesSchema;
+  relationships: RelationshipsSchema;
+}
+
 /**
  * A map of the most common field definitions to their JSON Schema
  * representations.
  */
 export async function basicMappings(loader: Loader) {
-  let mappings = new Map<typeof CardAPI.FieldDef, Schema>();
+  let mappings = new Map<typeof CardAPI.FieldDef, AttributesSchema>();
 
   let string: typeof import('https://cardstack.com/base/string') =
     await loader.import('https://cardstack.com/base/string');
@@ -154,14 +159,14 @@ export async function basicMappings(loader: Loader) {
 
 function getPrimitiveType(
   def: typeof CardAPI.BaseDef,
-  mappings: Map<typeof CardAPI.BaseDef, Schema>,
+  mappings: Map<typeof CardAPI.BaseDef, AttributesSchema>,
 ) {
   // If we go beyond fieldDefs there are no matching mappings to use
   if (!('isFieldDef' in def) || !def.isFieldDef) {
     return undefined;
   }
   if (mappings.has(def)) {
-    return { ...mappings.get(def) } as Schema;
+    return { ...mappings.get(def) } as AttributesSchema;
   } else {
     // Try the parent class, recurse up until we hit a type recognised
     return getPrimitiveType(Object.getPrototypeOf(def), mappings);
@@ -180,11 +185,11 @@ function getPrimitiveType(
  * @param mappings - A map of field definitions to JSON schema
  * @returns The generated patch call specification as JSON schema
  */
-function generatePatchCallSpecification(
+function generateJsonSchemaForContainsFields(
   def: typeof CardAPI.BaseDef,
   cardApi: typeof CardAPI,
-  mappings: Map<typeof CardAPI.FieldDef, Schema>,
-): Schema | undefined {
+  mappings: Map<typeof CardAPI.FieldDef, AttributesSchema>,
+): AttributesSchema | undefined {
   // If we're looking at a primitive field we can get the schema
   if (primitive in def) {
     return getPrimitiveType(def, mappings);
@@ -212,11 +217,11 @@ function generatePatchCallSpecification(
       continue;
     }
 
-    let fieldSchemaForSingleItem = generatePatchCallSpecification(
+    let fieldSchemaForSingleItem = generateJsonSchemaForContainsFields(
       field.card,
       cardApi,
       mappings,
-    ) as Schema | undefined;
+    ) as AttributesSchema | undefined;
     // This happens when we have no known schema for the field type
     if (fieldSchemaForSingleItem == undefined) {
       continue;
@@ -244,7 +249,7 @@ type RelationshipFieldInfo = {
   description?: string;
 };
 
-function generatePatchCallRelationshipsSpecification(
+function generateJsonSchemaForLinksToFields(
   def: typeof CardAPI.BaseDef,
   cardApi: typeof CardAPI,
 ): RelationshipsSchema | undefined {
@@ -258,7 +263,6 @@ function generatePatchCallRelationshipsSpecification(
   let schema: RelationshipsSchema = {
     type: 'object',
     properties: {},
-    required: [],
   };
   for (let rel of relationships) {
     let relSchema: LinksToSchema = {
@@ -281,6 +285,7 @@ function generatePatchCallRelationshipsSpecification(
             type: 'array',
             items: relSchema,
           };
+    schema.required = schema.required || [];
     schema.required.push(rel.flatFieldName);
     if (rel.description) {
       schema.properties[rel.flatFieldName].description = rel.description;
@@ -335,15 +340,13 @@ function generateRelationshipFieldsInfo(
  * @param mappings - A map of field definitions to JSON schema
  * @returns The generated patch call specification as JSON schema
  */
-export function generateCardPatchCallSpecification(
+export function generateJsonSchemaForCardType(
   def: typeof CardAPI.CardDef,
   cardApi: typeof CardAPI,
-  mappings: Map<typeof CardAPI.FieldDef, Schema>,
-):
-  | { attributes: Schema }
-  | { attributes: Schema; relationships: RelationshipsSchema } {
-  let schema = generatePatchCallSpecification(def, cardApi, mappings) as
-    | Schema
+  mappings: Map<typeof CardAPI.FieldDef, AttributesSchema>,
+): CardSchema {
+  let schema = generateJsonSchemaForContainsFields(def, cardApi, mappings) as
+    | AttributesSchema
     | undefined;
   if (schema == undefined) {
     return {
@@ -351,18 +354,23 @@ export function generateCardPatchCallSpecification(
         type: 'object',
         properties: {},
       },
+      relationships: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
     };
   } else {
-    let relationships = generatePatchCallRelationshipsSpecification(
-      def,
-      cardApi,
-    );
+    let relationships = generateJsonSchemaForLinksToFields(def, cardApi);
     if (
       !relationships ||
       !('required' in relationships) ||
-      !relationships.required.length
+      !(relationships.required?.length ?? 0)
     ) {
-      return { attributes: schema };
+      return {
+        attributes: schema,
+        relationships: { type: 'object', properties: {} },
+      };
     }
     return {
       attributes: schema,
@@ -383,16 +391,26 @@ export function getPatchTool(
       parameters: {
         type: 'object',
         properties: {
-          card_id: {
-            type: 'string',
-            const: attachedOpenCardId, // Force the valid card_id to be the id of the card being patched
-          },
           description: {
             type: 'string',
           },
-          ...patchSpec,
+          attributes: {
+            type: 'object',
+            properties: {
+              cardId: {
+                type: 'string',
+                const: attachedOpenCardId, // Force the valid card_id to be the id of the card being patched
+              },
+              patch: {
+                type: 'object',
+                properties: {
+                  ...patchSpec,
+                },
+              },
+            },
+          },
         },
-        required: ['card_id', 'attributes', 'description'],
+        required: ['attributes', 'description'],
       },
     },
   };
@@ -432,15 +450,20 @@ export function getSearchTool() {
           description: {
             type: 'string',
           },
-          filter: {
+          attributes: {
             type: 'object',
             properties: {
-              contains: containsFilterProperty,
-              eq: eqCardTypeFilterProperty,
+              filter: {
+                type: 'object',
+                properties: {
+                  contains: containsFilterProperty,
+                  eq: eqCardTypeFilterProperty,
+                },
+              },
             },
           },
         },
-        required: ['filter', 'description'],
+        required: ['attributes', 'description'],
       },
     },
   };
diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts
index 774116071d..1ca770d5e8 100644
--- a/packages/runtime-common/index.ts
+++ b/packages/runtime-common/index.ts
@@ -61,6 +61,7 @@ export interface RealmPrerenderedCards {
 import { RealmPaths, type LocalPath } from './paths';
 import { CardTypeFilter, EveryFilter, Query } from './query';
 import { Loader } from './loader';
+export * from './commands';
 export * from './constants';
 export * from './queue';
 export * from './expression';