@koi-language/koi 1.0.5 → 1.1.0

package/examples/actions-demo.koi

@@ -7,12 +7,11 @@
 // - return: Return results
 // ============================================================
 
-package "demo.koi.actions"
-
 role Worker { can execute }
+role Coordinator { can execute, can delegate }
 role LoggerRole { can execute }
 
-Agent Logger : LoggerRole {
+agent Logger : LoggerRole {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 150 }
 
   state {
@@ -51,7 +50,7 @@ Agent Logger : LoggerRole {
   }
 }
 
-Agent TaskProcessor : Worker {
+agent TaskProcessor : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 300 }
 
   state {
@@ -128,13 +127,13 @@ Agent TaskProcessor : Worker {
   }
 }
 
-Team LoggingTeam {
-  logger = Logger
-  processor = TaskProcessor
+team LoggingTeam {
+  logger: Logger
+  processor: TaskProcessor
 }
 
-Agent Orchestrator : Worker {
-  uses Team LoggingTeam
+agent Orchestrator : Coordinator {
+  uses team LoggingTeam
 
   on start(args: Json) {
     console.log("🎯 Actions Demo Starting...")

package/examples/activists-dialogue.koi

@@ -0,0 +1,75 @@
+role Worker { can execute }
+role Coordinator { can execute, can delegate }
+
+team TestTeam {
+  leftWingActivist: LeftWingActivist
+  rightWingActivist: RightWingActivist
+}
+
+// Right-wing activist agent that gives radical opinions
+agent RightWingActivist : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on ask(args: Json) {
+    playbook """
+    You are a radical right-wing activist with strong ideas.
+
+    Context: ${args.context}
+
+    Give your opinion on the topic proposed by the coordinator, and criticize the left-wing activist's intervention, SUPER aggressively.
+    Provide data and facts about the topic and criticize the left-wing activist's intervention, SUPER aggressively.
+    Maximum a couple of short and direct sentences.
+
+    Return ONLY: { "answer": "your intervention here" }
+    """
+  }
+}
+
+// Left-wing activist agent that responds with radical ideas
+agent LeftWingActivist : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on respond(args: Json) {
+    playbook """
+    You are a radical left-wing activist with strong ideas.
+
+    Context: ${args.context}
+
+    Give your opinion on the topic proposed by the coordinator, and criticize the right-wing activist's intervention, SUPER aggressively.
+    Provide data and facts about the topic and criticize the right-wing activist's intervention, SUPER aggressively.
+    Maximum a couple of short and direct sentences.
+
+    Return ONLY: { "answer": "your intervention here" }
+    """
+  }
+}
+
+// Coordinator that orchestrates the dialogue
+agent DialogueCoordinator : Coordinator {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  uses team TestTeam
+
+  on startDialogue(args: Json) {
+    playbook """
+    You are the coordinator of a dialogue between a right-wing and a left-wing activist for 3 turns.
+
+    Propose a current topic from today's politics and show that topic to the user.
+
+    Give the floor to one agent, then the other.
+
+    Print the dialogue like this:
+    - 🔵 Right-wing activist: <intervention here>
+    - 🔴 Left-wing activist: <intervention here>
+
+    Each activist must know what the other activist has said; it is your job to send each activist what the other one has said.
+
+    After 3 rounds, ask the user if they want the dialogue to continue or not. If they do not want it to continue, finish by showing:
+    ✨ Dialogue completed!
+    If they want it to continue, do another round of 3 turns and ask again if they want the dialogue to continue or not.
+
+    """
+  }
+}
+
+run DialogueCoordinator.startDialogue({})

package/examples/agent-dialogue.koi

@@ -0,0 +1,66 @@
+role Worker { can execute }
+role Coordinator { can execute, can delegate }
+
+team TestTeam {
+  philosopher: Philosopher
+  poet: Poet
+}
+
+// Philosopher agent that asks deep questions
+agent Philosopher : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on ask(args: Json) {
+    playbook """
+    You are a philosopher who asks deep questions.
+
+    Context: ${args.context}
+
+    Generate ONE brief philosophical question (maximum 2 sentences).
+
+    Return ONLY: { "question": "your question here" }
+    """
+  }
+}
+
+// Poet agent that responds in a poetic manner
+agent Poet : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on respond(args: Json) {
+    playbook """
+    You are a poet who responds in a metaphorical way.
+
+    Question: "${args.question}"
+
+    Respond poetically (maximum 2 sentences).
+
+    Return ONLY: { "answer": "your answer here" }
+    """
+  }
+}
+
+// Coordinator that orchestrates the dialogue
+agent DialogueCoordinator : Coordinator {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  uses team TestTeam
+
+  on startDialogue(args: Json) {
+    playbook """
+    Coordinate a dialogue between Philosopher and Poet for 3 turns.
+
+    In each turn:
+    First have the philosopher ask a question and then have the poet respond to that question.
+    Print the dialogue like this:
+    - 🤔 Philosopher: <question here>
+    - 🎭 Poet: <answer here>
+
+    After 3 rounds, finish by showing:
+    ✨ Dialogue completed!
+
+    """
+  }
+}
+
+run DialogueCoordinator.startDialogue({})

package/examples/chess.koi

@@ -0,0 +1,19 @@
+// Demo: Iteration Actions (repeat and while)
+// Shows how to repeat actions fixed number of times or until condition
+
+role Worker { can execute }
+
+agent Assistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on test_while(args: Json) {
+    playbook """
+    Play chess with the user.
+    On each turn you show the board, and the user says where to move with a combination like A2 to A4, B3 to C3
+    Then you make your move and show the board as it looks after your move.
+    End the game when someone wins or if the user expresses their wish to stop.
+    """
+  }
+}
+
+run Assistant.test_while({})

package/examples/counter.koi

@@ -3,12 +3,12 @@
 // Simple stateful agent that counts using playbooks
 // ============================================================
 
-package "demo.koi.counter"
-
 role Worker { can execute }
+role Coordinator { can execute, can delegate }
 
-Agent Counter : Worker {
+agent Counter : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+  amnesia = true
 
   state {
     count: Int = 0
@@ -16,111 +16,62 @@ Agent Counter : Worker {
 
   on increment(args: Json) {
     playbook """
-    You are a counter agent. Increment the internal counter by 1 and return the new value.
-
-    Current state: state.count = ${state.count}
-
-    Your task:
-    1. Calculate the new count by adding 1 to the current count
-    2. Return a JSON response with BOTH the result AND the state update
-
-    Return ONLY this exact JSON structure (no markdown, no explanations):
-    {
-      "state_updates": {
-        "count": [new count value after incrementing]
-      },
-      "count": [new count value after incrementing]
-    }
-
-    Example: If current count is 5, return:
-    {
-      "state_updates": { "count": 6 },
-      "count": 6
-    }
+    You are a counter agent. Increment the internal counter by 1.
+    Current count: ${state.count}
+    Calculate the new count and return it. Use state_updates to persist the new value.
     """
   }
 
   on get(args: Json) {
     playbook """
     You are a counter agent. Return the current counter value without modifying it.
-
-    Current state: state.count = ${state.count}
-
-    Return ONLY this exact JSON structure (no markdown, no explanations):
-    {
-      "count": ${state.count}
-    }
+    Current count: ${state.count}
     """
   }
 
   on reset(args: Json) {
     playbook """
     You are a counter agent. Reset the counter to zero.
-
-    Current state: state.count = ${state.count}
-
-    Your task:
-    1. Reset the counter to 0
-    2. Return a JSON response with BOTH the result AND the state update
-
-    Return ONLY this exact JSON structure (no markdown, no explanations):
-    {
-      "state_updates": {
-        "count": 0
-      },
-      "count": 0
-    }
+    Current count: ${state.count}
+    Reset to 0 and return. Use state_updates to persist the new value.
     """
   }
 
   on incrementBy(args: Json) {
     playbook """
     You are a counter agent. Increment the counter by a specific amount.
-
-    Current state: state.count = ${state.count}
-    Amount to increment: args.amount = ${args.amount || 1}
-
-    Your task:
-    1. Calculate the new count by adding args.amount to the current count
-    2. Return a JSON response with BOTH the result AND the state update
-
-    Return ONLY this exact JSON structure (no markdown, no explanations):
-    {
-      "state_updates": {
-        "count": [new count value]
-      },
-      "count": [new count value],
-      "incremented": [amount that was added]
-    }
+    Current count: ${state.count}
+    Amount to add: ${args.amount || 1}
+    Calculate the new count and return it. Use state_updates to persist the new value.
     """
   }
 }
 
-Team CounterTeam {
-  counter = Counter
+team CounterTeam {
+  counter: Counter
 }
 
-Agent Orchestrator : Worker {
-  uses Team CounterTeam
+agent Orchestrator : Coordinator {
+  uses team CounterTeam
 
   on start(args: Json) {
     console.log("🔢 Counter Test Starting...")
     console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
 
     const r1 =
-      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+      await send peers.event("increment").role(Worker).any()({}) timeout 30s
     console.log("✓ After increment 1:", r1)
 
     const r2 =
-      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+      await send peers.event("increment").role(Worker).any()({}) timeout 305s
     console.log("✓ After increment 2:", r2)
 
     const r3 =
-      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+      await send peers.event("increment").role(Worker).any()({}) timeout 305s
     console.log("✓ After increment 3:", r3)
 
     const current =
-      await send peers.event("get").role(Worker).any()({}) timeout 5s
+      await send peers.event("get").role(Worker).any()({}) timeout 30s
     console.log("✓ Current value:", current)
 
     console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")

package/examples/delegation-test.koi

@@ -1,10 +1,15 @@
-package "test.delegation"
-
 role Worker { can execute }
+role Coordinator { can execute, can delegate }
+
+team TestTeam {
+  translator: Translator
+  wordCounter: WordCounter
+}
 
 // Simple translator agent
-Agent Translator : Worker {
+agent Translator : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
+  amnesia = true
 
   on translate(args: Json) {
     playbook """
@@ -15,8 +20,9 @@ Agent Translator : Worker {
 }
 
 // Simple counter agent
-Agent WordCounter : Worker {
+agent WordCounter : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
+  amnesia = true
 
   on count(args: Json) {
     playbook """
@@ -27,24 +33,16 @@ Agent WordCounter : Worker {
 }
 
 // Orchestrator that chains tasks
-Agent Orchestrator : Worker {
+agent Orchestrator : Coordinator {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
+  uses team TestTeam
 
   on processText(args: Json) {
     playbook """
-    Task: Translate "${args.text}" to Spanish, then count the words.
-
-    Create a plan with 2 actions:
-    1. Translate the text to Spanish
-    2. Count the words in the translation
-
-    Return JSON with actions array:
-    {
-      "actions": [
-        { "intent": "translate to spanish", "data": { "text": "${args.text}", "language": "spanish" } },
-        { "intent": "count words", "data": { "text": "\${previousResult.translated}" } }
-      ]
-    }
+    Prompt the user to enter a sentence.
+    Translate the sentence to Spanish.
+    Count the words in the translation.
+    Print the original sentence, the translation, and the word count.
     """
   }
 }

package/examples/dialog-demo.koi

@@ -0,0 +1,20 @@
+// Demo: Iteration Actions (repeat and while)
+// Shows how to repeat actions fixed number of times or until condition
+
+role Worker { can execute }
+
+agent Assistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on test_while(args: Json) {
+    playbook """
+    Talk with the user until they say goodbye to you.
+    Start the conversation by bringing up a topic of general interest, about politics, sports, science, whatever you prefer.
+    Talk with the user until they express their intention to end the conversation, in which case say goodbye cordially and end the conversation.
+    When you ask the user something, let them express themselves. Do not give them a set of options, instead let them express themselves freely.
+    SUPER IMPORTANT, The first thing you must do is introduce yourself. Your name is Koi, so ask for their name and greet them cordially. Then start the conversation.
+    """
+  }
+}
+
+run Assistant.test_while({})

package/examples/hello-world.koi

@@ -1,52 +1,16 @@
-// ============================================================
-// Koi — Hello World with LLM Playbook
-// Simple example showing playbook execution with real LLM
-// ============================================================
-
-package "demo.koi.helloworld"
+// Demo: Iteration Actions (repeat and while)
+// Shows how to repeat actions fixed number of times or until condition
 
 role Worker { can execute }
 
-// Agent with playbook only (will execute with LLM)
-Agent Greeter : Worker {
-  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.7, max_tokens: 200 }
+agent Assistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
 
-  on greet(args: Json) {
+  on test_while(args: Json) {
     playbook """
-    You are a friendly greeter. Generate a warm, creative greeting for the person whose name is in args.name.
-
-    Return a JSON object with this exact structure:
-    {
-      "greeting": "Your creative greeting here",
-      "language": "english",
-      "style": "friendly"
-    }
-
-    Make the greeting unique and warm, but keep it under 50 words.
+    Ask the user for their name, then greet them warmly
     """
   }
 }
 
-Team HelloTeam {
-  greeter = Greeter
-}
-
-// Orchestrator with procedural code
-Agent Orchestrator : Worker {
-  uses Team HelloTeam
-
-  on start(args: Json) {
-    const name = args.name
-
-    const result =
-      await send peers.event("greet").role(Worker).any()({ name: name }) timeout 30s
-
-    return {
-      success: true,
-      name: name,
-      response: result
-    }
-  }
-}
-
-run Orchestrator.start({ name: "World" })
+run Assistant.test_while({})

package/examples/mcp-stdio-demo.koi

@@ -0,0 +1,29 @@
+// ============================================================
+// Koi — MCP Stdio Server Demo
+// Demonstrates connecting to external MCP servers via stdio
+// ============================================================
+
+role Worker { can execute }
+
+// Declare an MCP server that communicates via stdio
+// The server is spawned as a subprocess and tools are discovered via JSON-RPC 2.0
+mcp echoServer = {
+  command: "node",
+  args: ["examples/utils/echo-mcp-server.js"]
+}
+
+// Agent that uses the MCP server's tools
+agent MCPAgent : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+  uses mcp echoServer
+
+  on testEcho(args: Json) {
+    playbook """
+    Use the echo MCP server to echo back the message: "${args.message}"
+    Then print the result.
+    Return the echo result.
+    """
+  }
+}
+
+run MCPAgent.testEcho({ message: "Hello from Koi MCP!" })

package/examples/memory-test.koi

@@ -0,0 +1,49 @@
+role Worker { can execute }
+role Coordinator { can execute, can delegate }
+
+team MemoryTeam {
+  assistant: MemoryAssistant
+}
+
+// Agent that should remember previous interactions
+agent MemoryAssistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on ask(args: Json) {
+    playbook """
+    ${args.question}
+
+    IMPORTANT: If you have memory of previous conversations, EXPLICITLY mention what you were asked before and what you answered.
+    If it's your first time, say that this is your first interaction.
+
+    Respond in English, maximum 2 sentences.
+
+    Return ONLY: { "answer": "your response here" }
+    """
+  }
+}
+
+// Coordinator that calls the assistant 3 times to test memory
+agent MemoryCoordinator : Coordinator {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  uses team MemoryTeam
+
+  on start(args: Json) {
+    playbook """
+    You will ask the MemoryAssistant 3 questions, one by one, to check if it remembers the previous ones.
+
+    1. Ask it: "What is the capital of France?"
+    2. Print its response with: Response 1: <response>
+    3. Ask it: "And the capital of Germany?"
+    4. Print its response with: Response 2: <response>
+    5. Ask it: "What have I asked you before? List the previous questions and your answers."
+    6. Print its response with: Response 3 (memory test): <response>
+
+    At the end print:
+    Memory test completed
+    """
+  }
+}
+
+run MemoryCoordinator.start({})

package/examples/mobile-mcp-demo.koi

@@ -0,0 +1,32 @@
+// ============================================================
+// Koi — Mobile MCP Demo
+// Controls a mobile device via the mobile-mcps MCP server.
+// Requires: Android emulator/device or iOS simulator running.
+// Usage: GEMINI_API_KEY=... koi run examples/mobile-mcp-demo.koi
+// ============================================================
+
+role Worker { can execute }
+
+mcp mobile = {
+  command: "node",
+  args: ["/path/to/mcp-server.js"],
+  //env: { "GEMINI_API_KEY": "" }
+}
+
+agent MobileAgent : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+  uses mcp mobile
+
+  on automate(args: Json) {
+    playbook """
+    Automate the mobile device to accomplish this goal: "${args.goal}"
+    1. List available devices to find a target.
+    2. Start the agent with the goal on the first available device.
+    3. Return the agent result.
+    """
+  }
+}
+
+run MobileAgent.automate({ goal: "Open maps and search for Rome, then in Rome find the street where the Trevi Fountain is located and show a photo" })
+
+