@koi-language/koi 1.0.5 → 1.1.0

package/examples/.build/hello-world.ts

@@ -0,0 +1,77 @@
+// Generated from hello-world.koi
+// Using local runtime from KOI_RUNTIME_PATH: /Users/antonioparraga/Git/Koi-lang/Koi/src/runtime
+import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from 'file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/index.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.SkillRegistry = SkillRegistry;
+globalThis.skillSelector = skillSelector;
+globalThis.registry = registry;
+globalThis.mcpRegistry = mcpRegistry;
+
+// ============================================================
+// Pre-computed Affordances (Build-time Cache)
+// Generated at: 2026-02-16T18:21:18.630Z
+// Total agents: 1
+// Total agent affordances: 1
+// Total skills: 0
+// Total skill affordances: 0
+// This avoids embedding API calls at runtime
+// ============================================================
+
+const CACHED_AFFORDANCES = {
+  "Assistant": {
+    "test_while": {
+      "description": "Ask the user for their name, then greet them warmly.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  }
+};
+
+const CACHED_SKILL_AFFORDANCES = {};
+
+const Worker = new Role('Worker', ['execute']);
+
+const Assistant = new Agent({
+  name: 'Assistant',
+  role: Worker,
+  llm: { provider: "openai", model: "gpt-5.2" },
+  handlers: {
+    test_while: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Ask the user for their name, then greet them warmly";
+      handler.__description__ = "Ask the user for their name, then greet them warmly.";
+      return handler;
+    })(),
+  }
+});
+
+
+// Main execution function
+(async () => {
+  // Register agents with router
+  const { agentRouter } = await import('file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/router.js');
+
+  await agentRouter.register(Assistant, CACHED_AFFORDANCES['Assistant']);
+
+  // Execute
+  const result = await Assistant.handle('test_while', {});
+  // Result handled by actions
+
+  const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };
+  process.on('SIGINT', _gracefulShutdown);
+  process.on('SIGTERM', _gracefulShutdown);
+
+  await mcpRegistry.disconnectAll();
+  process.exit(0);
+})().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+//# sourceMappingURL=hello-world.ts.map

package/examples/.build/hello-world.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["hello-world.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;AAEA","file":"hello-world.koi.js"}

package/examples/.build/lover-dialog-demo.ts

@@ -0,0 +1,77 @@
+// Generated from lover-dialog-demo.koi
+// Using local runtime from KOI_RUNTIME_PATH: /Users/antonioparraga/Git/Koi-lang/Koi/src/runtime
+import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from 'file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/index.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.SkillRegistry = SkillRegistry;
+globalThis.skillSelector = skillSelector;
+globalThis.registry = registry;
+globalThis.mcpRegistry = mcpRegistry;
+
+// ============================================================
+// Pre-computed Affordances (Build-time Cache)
+// Generated at: 2026-02-16T18:39:52.762Z
+// Total agents: 1
+// Total agent affordances: 1
+// Total skills: 0
+// Total skill affordances: 0
+// This avoids embedding API calls at runtime
+// ============================================================
+
+const CACHED_AFFORDANCES = {
+  "Assistant": {
+    "test_while": {
+      "description": "Roleplay as the user’s loving partner, chat freely (including sex) until they say goodbye, then warmly end.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  }
+};
+
+const CACHED_SKILL_AFFORDANCES = {};
+
+const Worker = new Role('Worker', ['execute']);
+
+const Assistant = new Agent({
+  name: 'Assistant',
+  role: Worker,
+  llm: { provider: "openai", model: "gpt-5.2" },
+  handlers: {
+    test_while: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "You are the girlfriend / boyfriend of the end user. You are in love with the end user.\n\n    Talk with the user until they say goodbye to you. Feel free to talk about sex.\n    Talk with the user until they express their intention to end the conversation, in which case you should end the conversation with a final lovely saludation.\n    When you ask the user something, let them express themselves. Do not give them a set of options, instead let them express themselves freely.";
+      handler.__description__ = "Roleplay as the user’s loving partner, chat freely (including sex) until they say goodbye, then warmly end.";
+      return handler;
+    })(),
+  }
+});
+
+
+// Main execution function
+(async () => {
+  // Register agents with router
+  const { agentRouter } = await import('file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/router.js');
+
+  await agentRouter.register(Assistant, CACHED_AFFORDANCES['Assistant']);
+
+  // Execute
+  const result = await Assistant.handle('test_while', {});
+  // Result handled by actions
+
+  const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };
+  process.on('SIGINT', _gracefulShutdown);
+  process.on('SIGTERM', _gracefulShutdown);
+
+  await mcpRegistry.disconnectAll();
+  process.exit(0);
+})().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+//# sourceMappingURL=lover-dialog-demo.ts.map

package/examples/.build/lover-dialog-demo.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["lover-dialog-demo.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;AAEA","file":"lover-dialog-demo.koi.js"}

package/examples/.build/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/examples/.build/registry-interactive-demo.ts

@@ -0,0 +1,202 @@
+// Generated from registry-interactive-demo.koi
+// Using local runtime from KOI_RUNTIME_PATH: /Users/antonioparraga/Git/Koi-lang/Koi/src/runtime
+import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from 'file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/index.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.SkillRegistry = SkillRegistry;
+globalThis.skillSelector = skillSelector;
+globalThis.registry = registry;
+globalThis.mcpRegistry = mcpRegistry;
+
+// ============================================================
+// Pre-computed Affordances (Build-time Cache)
+// Generated at: 2026-02-16T18:12:17.085Z
+// Total agents: 2
+// Total agent affordances: 8
+// Total skills: 0
+// Total skill affordances: 0
+// This avoids embedding API calls at runtime
+// ============================================================
+
+const CACHED_AFFORDANCES = {
+  "UserManager": {
+    "createAllUser": {
+      "description": "Create multiple users with specified attributes and save them to the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "createUser": {
+      "description": "Create a single user with specified attributes and save to the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "getUser": {
+      "description": "Retrieve and return user data from the registry using the user's unique key.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "listAllUsers": {
+      "description": "List all users in the registry, returning their data without additional wrappers.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "findAdults": {
+      "description": "Find and return all users aged 18 or older from the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "updateUserAge": {
+      "description": "Update a user's age while preserving all other fields and save the updated object.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "deleteUser": {
+      "description": "Delete a user from the registry using their unique identifier.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  },
+  "Demo": {
+    "start": {
+      "description": "Run a user registry demo, guiding the user through various actions and displaying results.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  }
+};
+
+const CACHED_SKILL_AFFORDANCES = {};
+
+const Worker = new Role('Worker', ['execute', 'registry']);
+
+const Manager = new Role('Manager', ['execute', 'delegate']);
+
+const UserManager = new Agent({
+  name: 'UserManager',
+  role: Worker,
+  llm: { provider: "openai", model: "gpt-4o-mini" },
+  amnesia: true,
+  handlers: {
+    createAllUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Create all given users via args, with the following attributes\n    - name, age, email\n\n    Save all to registry with key \"user:id being id an unique identifier\".\n    Include all fields plus a createdAt timestamp.\n    Return: { \"success\": true, \"message\": \"Users created\" }\n\n    DO NOT add print actions - just return the data.";
+      handler.__description__ = "Create multiple users with specified attributes and save them to the registry.";
+      return handler;
+    })(),
+    createUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Create a new user with:\n    - name: ${args.name}\n    - age: ${args.age}\n    - email: ${args.email}\n\n    Save to registry with key \"user:${args.id}\".\n    Include all fields plus a createdAt timestamp.\n    Return: { \"success\": true, \"message\": \"User created\" }\n\n    DO NOT add print actions - just return the data.";
+      handler.__description__ = "Create a single user with specified attributes and save to the registry.";
+      return handler;
+    })(),
+    getUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Get user ${args.id} from registry.\n\n    Use registry_get with key \"user:${args.id}\".\n    Extract the .value field from the registry_get result (which contains the user data).\n    Return ONLY the user data object (name, age, email, createdAt) without any wrapper.";
+      handler.__description__ = "Retrieve and return user data from the registry using the user's unique key.";
+      return handler;
+    })(),
+    listAllUsers: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "List all users in the registry.\n\n    EXACT STEPS:\n    1. Use registry_search with an empty query {} to get ALL users, store with ID \"a1\"\n    2. Extract just the user data (the .value field) from each result\n    3. Return: { \"count\": <count from a1>, \"users\": <array of user value objects, NOT the full {key, value} wrappers> }\n\n    Example: If a1.output.results = [{key: \"user:001\", value: {name: \"Alice\", age: 30}}, ...]\n    Then return: { \"count\": 2, \"users\": [{name: \"Alice\", age: 30}, ...] }\n\n    CRITICAL: Extract ONLY the .value objects so caller can access with .users[0].name directly\n    DO NOT use format action - return a real array!";
+      handler.__description__ = "List all users in the registry, returning their data without additional wrappers.";
+      return handler;
+    })(),
+    findAdults: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Find all users aged 18 or older using registry search with query: { \"age\": { \"$gte\": 18 } }\n\n    EXACT STEPS:\n    1. Use registry_search with query: { \"age\": { \"$gte\": 18 } }\n    2. Return: { \"count\": [count from search], \"adults\": [results array] }\n\n    DO NOT add print actions - just return the data!";
+      handler.__description__ = "Find and return all users aged 18 or older from the registry.";
+      return handler;
+    })(),
+    updateUserAge: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Update user ${args.id}'s age to ${args.age}.\n\n    EXACT STEPS:\n    1. Use registry_get with key \"user:${args.id}\", store with ID \"a1\"\n    2. Take the full user object from \\${a1.output.value}\n    3. Modify ONLY the age field to ${args.age}, keep all other fields (name, email, createdAt, etc.)\n    4. Use registry_set with key \"user:${args.id}\" and the complete updated object\n    5. Return: { \"success\": true, \"message\": \"Age updated\" }\n\n    CRITICAL: Preserve ALL existing fields when saving!";
+      handler.__description__ = "Update a user's age while preserving all other fields and save the updated object.";
+      return handler;
+    })(),
+    deleteUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Delete the user from the registry with ID ${args.id}.\n\n    EXACT STEPS:\n    1. Use registry_delete with key \"user:\\${args.id}\"\n    2. Return: { \"success\": true, \"message\": \"User deleted\" }";
+      handler.__description__ = "Delete a user from the registry using their unique identifier.";
+      return handler;
+    })(),
+  }
+});
+
+const RegistryTeam = new Team('RegistryTeam', {
+  userManager: UserManager,
+});
+
+const Demo = new Agent({
+  name: 'Demo',
+  role: Manager,
+  usesTeams: [RegistryTeam],
+  peers: RegistryTeam, // Auto-assigned from uses Team
+  llm: { provider: "openai", model: "gpt-4o-mini" },
+  handlers: {
+    start: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Run a user registry demo.\n\n    Show the header (just the very first time):\n    ╔══════════════════════════════════════════════════╗\n    ║  Registry with Playbook Demo                     ║\n    ╚══════════════════════════════════════════════════╝\n\n    Them ask the user what it wants: create / consult / modify / delete any user and do what the user wants.\n    Aks as many info as you need to the user to perform the action the user wants from you.\n\n    After performing an action, ask the user if it want to continuer, and in that case ask again what it wants (loop)\n\n    If the user wnats to list the users, for each one show in a markdown table: Mr or Ms depending on whether they are male or female (deduce this from the name) and then {the user's name}, age {their age}\"\n\n    Before exiting, print:\n    ╔══════════════════════════════════════════════════╗\n    ║  Demo completed successfully!                    ║\n    ╚══════════════════════════════════════════════════╝";
+      handler.__description__ = "Run a user registry demo, guiding the user through various actions and displaying results.";
+      return handler;
+    })(),
+  }
+});
+
+
+// Main execution function
+(async () => {
+  // Register agents with router
+  const { agentRouter } = await import('file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/router.js');
+
+  await agentRouter.register(UserManager, CACHED_AFFORDANCES['UserManager']);
+  await agentRouter.register(Demo, CACHED_AFFORDANCES['Demo']);
+
+  // Execute
+  const result = await Demo.handle('start', {});
+  // Result handled by actions
+
+  const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };
+  process.on('SIGINT', _gracefulShutdown);
+  process.on('SIGTERM', _gracefulShutdown);
+
+  await mcpRegistry.disconnectAll();
+  process.exit(0);
+})().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+//# sourceMappingURL=registry-interactive-demo.ts.map

package/examples/.build/registry-interactive-demo.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["registry-interactive-demo.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;AACA;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkGA;;;;AAKA","file":"registry-interactive-demo.koi.js"}

package/examples/.build/registry-playbook-demo.ts

@@ -0,0 +1,201 @@
+// Generated from registry-playbook-demo.koi
+// Using local runtime from KOI_RUNTIME_PATH: /Users/antonioparraga/Git/Koi-lang/Koi/src/runtime
+import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from 'file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/index.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.SkillRegistry = SkillRegistry;
+globalThis.skillSelector = skillSelector;
+globalThis.registry = registry;
+globalThis.mcpRegistry = mcpRegistry;
+
+// ============================================================
+// Pre-computed Affordances (Build-time Cache)
+// Generated at: 2026-02-16T17:31:22.509Z
+// Total agents: 2
+// Total agent affordances: 8
+// Total skills: 0
+// Total skill affordances: 0
+// This avoids embedding API calls at runtime
+// ============================================================
+
+const CACHED_AFFORDANCES = {
+  "UserManager": {
+    "createAllUser": {
+      "description": "Create multiple users with specified attributes and save them to the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "createUser": {
+      "description": "Create a single user with specified attributes and save to the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "getUser": {
+      "description": "Retrieve and return user data from the registry using the user's unique key.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "listAllUsers": {
+      "description": "List all users in the registry and return their data without wrappers.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "findAdults": {
+      "description": "Find and return all users aged 18 or older from the registry.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "updateUserAge": {
+      "description": "Update a user's age while preserving all other fields and save the updated object.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    },
+    "deleteUser": {
+      "description": "Delete a user from the registry using their unique identifier.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  },
+  "Demo": {
+    "start": {
+      "description": "Run a demo showcasing user creation, retrieval, listing, searching, updating, and deletion.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  }
+};
+
+const CACHED_SKILL_AFFORDANCES = {};
+
+const Worker = new Role('Worker', ['execute', 'registry']);
+
+const Manager = new Role('Manager', ['execute', 'delegate']);
+
+const UserManager = new Agent({
+  name: 'UserManager',
+  role: Worker,
+  llm: { provider: "openai", model: "gpt-4o-mini" },
+  handlers: {
+    createAllUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Create all given users via args, with the following attributes\n    - name, age, email\n\n    Save all to registry with key \"user:id being id an unique identifier\".\n    Include all fields plus a createdAt timestamp.\n    Return: { \"success\": true, \"message\": \"Users created\" }\n\n    DO NOT add print actions - just return the data.";
+      handler.__description__ = "Create multiple users with specified attributes and save them to the registry.";
+      return handler;
+    })(),
+    createUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Create a new user with:\n    - name: ${args.name}\n    - age: ${args.age}\n    - email: ${args.email}\n\n    Save to registry with key \"user:${args.id}\".\n    Include all fields plus a createdAt timestamp.\n    Return: { \"success\": true, \"message\": \"User created\" }\n\n    DO NOT add print actions - just return the data.";
+      handler.__description__ = "Create a single user with specified attributes and save to the registry.";
+      return handler;
+    })(),
+    getUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Get user ${args.id} from registry.\n\n    Use registry_get with key \"user:${args.id}\".\n    Extract the .value field from the registry_get result (which contains the user data).\n    Return ONLY the user data object (name, age, email, createdAt) without any wrapper.";
+      handler.__description__ = "Retrieve and return user data from the registry using the user's unique key.";
+      return handler;
+    })(),
+    listAllUsers: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "List all users in the registry.\n\n    EXACT STEPS:\n    1. Use registry_search with an empty query {} to get ALL users, store with ID \"a1\"\n    2. Extract just the user data (the .value field) from each result\n    3. Return: { \"count\": <count from a1>, \"users\": <array of user value objects, NOT the full {key, value} wrappers> }\n\n    Example: If a1.output.results = [{key: \"user:001\", value: {name: \"Alice\", age: 30}}, ...]\n    Then return: { \"count\": 2, \"users\": [{name: \"Alice\", age: 30}, ...] }\n\n    CRITICAL: Extract ONLY the .value objects so caller can access with .users[0].name directly\n    DO NOT use format action - return a real array!";
+      handler.__description__ = "List all users in the registry and return their data without wrappers.";
+      return handler;
+    })(),
+    findAdults: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Find all users aged 18 or older using registry search with query: { \"age\": { \"$gte\": 18 } }\n\n    EXACT STEPS:\n    1. Use registry_search with query: { \"age\": { \"$gte\": 18 } }\n    2. Return: { \"count\": [count from search], \"adults\": [results array] }\n\n    DO NOT add print actions - just return the data!";
+      handler.__description__ = "Find and return all users aged 18 or older from the registry.";
+      return handler;
+    })(),
+    updateUserAge: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Update user ${args.id}'s age to ${args.age}.\n\n    EXACT STEPS:\n    1. Use registry_get with key \"user:${args.id}\", store with ID \"a1\"\n    2. Take the full user object from \\${a1.output.value}\n    3. Modify ONLY the age field to ${args.age}, keep all other fields (name, email, createdAt, etc.)\n    4. Use registry_set with key \"user:${args.id}\" and the complete updated object\n    5. Return: { \"success\": true, \"message\": \"Age updated\" }\n\n    CRITICAL: Preserve ALL existing fields when saving!";
+      handler.__description__ = "Update a user's age while preserving all other fields and save the updated object.";
+      return handler;
+    })(),
+    deleteUser: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Delete the user from the registry with ID ${args.id}.\n\n    EXACT STEPS:\n    1. Use registry_delete with key \"user:\\${args.id}\"\n    2. Return: { \"success\": true, \"message\": \"User deleted\" }";
+      handler.__description__ = "Delete a user from the registry using their unique identifier.";
+      return handler;
+    })(),
+  }
+});
+
+const RegistryTeam = new Team('RegistryTeam', {
+  userManager: UserManager,
+});
+
+const Demo = new Agent({
+  name: 'Demo',
+  role: Manager,
+  usesTeams: [RegistryTeam],
+  peers: RegistryTeam, // Auto-assigned from uses Team
+  llm: { provider: "openai", model: "gpt-4o-mini" },
+  handlers: {
+    start: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Run a user registry demo.\n\n    Show the header:\n    ╔══════════════════════════════════════════════════╗\n    ║  Registry with Playbook Demo                     ║\n    ╚══════════════════════════════════════════════════╝\n\n    1️⃣ Create these users:\n    - Alice: id=001, age=30, email=alice@example.com\n    - Bob: id=002, 17 years old, bob@example.com\n    - Charlie: id=003, age=25, email=charlie@example.com\n    - Diana: id=004, age is 35, diana@example.com\n    - Erika: id=005, age=28, email=erika@example.com\n    - Fernando: id=006, age=32, fernando@example.com\n    Show: \"   ✅ X users created\" where X is the number of users that were created\n\n    2️⃣ Get user 001\n    Show: \"   ✅ Found user: {the user's name}, age {their age}\"\n\n    3️⃣ List all users\n    Show: \"   ✅ Found {the number of users} users then for each one show in a markdown table: Mr or Ms depending on whether they are male or female (deduce this from the name) and then {the user's name}, age {their age}\"\n\n    4️⃣ Search for users older than 18 years\n    Show: \"   ✅ Found {the number found} adults\"\n\n    5️⃣ Update Bob's age (002) to 19 years old\n    Then get the updated user\n    Show: \"   ✅ Bob is now {his new age} years old\"\n\n    6️⃣ Delete Charlie (003)\n    Then list the remaining users\n    Show: \"   ✅ Remaining users: {the remaining count}\"\n\n    7️⃣ List all users again as you did in step 3️⃣\n    Show the users in a markdown table with the same format as in step 3️⃣\n\n    Show the footer:\n    ╔══════════════════════════════════════════════════╗\n    ║  Demo completed successfully!                    ║\n    ╚══════════════════════════════════════════════════╝";
+      handler.__description__ = "Run a demo showcasing user creation, retrieval, listing, searching, updating, and deletion.";
+      return handler;
+    })(),
+  }
+});
+
+
+// Main execution function
+(async () => {
+  // Register agents with router
+  const { agentRouter } = await import('file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/router.js');
+
+  await agentRouter.register(UserManager, CACHED_AFFORDANCES['UserManager']);
+  await agentRouter.register(Demo, CACHED_AFFORDANCES['Demo']);
+
+  // Execute
+  const result = await Demo.handle('start', {});
+  // Result handled by actions
+
+  const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };
+  process.on('SIGINT', _gracefulShutdown);
+  process.on('SIGTERM', _gracefulShutdown);
+
+  await mcpRegistry.disconnectAll();
+  process.exit(0);
+})().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+//# sourceMappingURL=registry-playbook-demo.ts.map

package/examples/.build/registry-playbook-demo.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["registry-playbook-demo.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;AACA;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiGA;;;;AAKA","file":"registry-playbook-demo.koi.js"}

package/examples/.build/tic-tac-toe.ts

@@ -0,0 +1,77 @@
+// Generated from tic-tac-toe.koi
+// Using local runtime from KOI_RUNTIME_PATH: /Users/antonioparraga/Git/Koi-lang/Koi/src/runtime
+import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from 'file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/index.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.SkillRegistry = SkillRegistry;
+globalThis.skillSelector = skillSelector;
+globalThis.registry = registry;
+globalThis.mcpRegistry = mcpRegistry;
+
+// ============================================================
+// Pre-computed Affordances (Build-time Cache)
+// Generated at: 2026-02-16T18:23:23.268Z
+// Total agents: 1
+// Total agent affordances: 1
+// Total skills: 0
+// Total skill affordances: 0
+// This avoids embedding API calls at runtime
+// ============================================================
+
+const CACHED_AFFORDANCES = {
+  "Assistant": {
+    "test_while": {
+      "description": "Plays tic-tac-toe by alternating moves, showing the board each turn, until win or stop.",
+      "confidence": 0.9,
+      "hasPlaybook": true
+    }
+  }
+};
+
+const CACHED_SKILL_AFFORDANCES = {};
+
+const Worker = new Role('Worker', ['execute']);
+
+const Assistant = new Agent({
+  name: 'Assistant',
+  role: Worker,
+  llm: { provider: "openai", model: "gpt-5.2" },
+  handlers: {
+    test_while: (() => {
+      const handler = async function(args) {
+        // This should not be called - playbook will be executed by LLM
+        throw new Error('Playbook-only handler called directly');
+      };
+      handler.__playbookOnly__ = true;
+      handler.__playbook__ = "Play tic-tac-toe with the user.\n    On each turn you show the board, and the user says where to move with a combination like A2, B3\n    Then you make your move and show the board as it looks after your move.\n    End the game when someone wins or if the user expresses their wish to stop.";
+      handler.__description__ = "Plays tic-tac-toe by alternating moves, showing the board each turn, until win or stop.";
+      return handler;
+    })(),
+  }
+});
+
+
+// Main execution function
+(async () => {
+  // Register agents with router
+  const { agentRouter } = await import('file:///Users/antonioparraga/Git/Koi-lang/Koi/src/runtime/router.js');
+
+  await agentRouter.register(Assistant, CACHED_AFFORDANCES['Assistant']);
+
+  // Execute
+  const result = await Assistant.handle('test_while', {});
+  // Result handled by actions
+
+  const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };
+  process.on('SIGINT', _gracefulShutdown);
+  process.on('SIGTERM', _gracefulShutdown);
+
+  await mcpRegistry.disconnectAll();
+  process.exit(0);
+})().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+//# sourceMappingURL=tic-tac-toe.ts.map

package/examples/.build/tic-tac-toe.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["tic-tac-toe.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;AAEA","file":"tic-tac-toe.koi.js"}