@globant/coda-windows-x64 1.0.0

package/assets/skills/create-extension/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: create-extension
+description: Create g-coda extensions that register tools, slash commands, lifecycle hooks, and providers. Use when the user wants to create, write, or scaffold a new extension, or asks about the extension API, tool registration, or command registration.
+---
+
+# Creating g-coda Extensions
+
+## Quick start
+
+An extension is a TypeScript file that exports `activate` or a `default` function receiving `ExtensionAPI`. Place it in `.coda/extensions/` (project) or `~/.coda/extensions/` (global).
+
+```typescript
+import { z, type ExtensionAPI, type AgentTool, type ToolContext } from "@globant/coda-core";
+
+export default function activate(api: ExtensionAPI): void {
+  // Register tools, commands, hooks, shortcuts, providers
+}
+```
+
+`@globant/coda-core` re-exports `z` (Zod) and `resolveGitWorkspaceRoot` so extensions only need one import source.
+
+## Extension locations
+
+| Priority | Source | Scope |
+|----------|--------|-------|
+| 1 | `.coda/extensions/*.ts` | Project-level (highest) |
+| 2 | `~/.coda/extensions/*.ts` | User-global |
+| 3 | `config.json` → `extensions[]` | Configured paths |
+| 4 | `-e ./path.ts` | CLI flag |
+
+Subdirectories with `package.json` containing `coda.extensions` or `index.ts` are also discovered.
+
+## Registering tools
+
+Tools are functions the LLM can call. Use Zod for parameter schemas.
+
+```typescript
+const myTool: AgentTool<MyParams, string> = {
+  name: "my_tool",
+  description: "Clear description of what the tool does and when to use it",
+  parameters: z.object({
+    query: z.string().describe("What to search for"),
+    limit: z.number().int().positive().optional().describe("Max results"),
+  }),
+  label: "My Tool",
+  execute: async (
+    toolCallId: string,
+    params: MyParams,
+    context: ToolContext,
+  ): Promise<string> => {
+    const cwd = context.cwd ?? process.cwd();
+    // Implementation here
+    return "result string returned to the LLM";
+  },
+};
+
+api.registerTool(myTool);
+```
+
+### AgentTool interface
+
+```typescript
+interface AgentTool<TParams = unknown, TResult = unknown> {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: z.ZodTypeAny;
+  readonly label: string;
+  execute(toolCallId: string, params: TParams, context: ToolContext): Promise<TResult>;
+}
+```
+
+### ToolContext (available inside execute)
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `cwd` | `string?` | Project directory |
+| `signal` | `AbortSignal?` | Cancellation signal |
+| `hitl` | `IHitlManager` | Human-in-the-loop prompts |
+| `operations` | `Operations` | `readFile`, `writeFile`, `listFiles` |
+| `sessionId` | `string` | Current session ID |
+| `mcp` | `IMCPService?` | MCP server access |
+| `onUpdate` | `(update) => void` | Stream progress updates |
+| `model` | `ToolContextModelInfo?` | Current model info |
+
+### Tool description tips
+
+- Start with the category in CAPS (e.g. `"SEMANTIC CODE SEARCH (colgrep)."`)
+- Explain when the LLM should choose this tool over alternatives
+- Include parameter examples in the description
+- For complex tools, use a `parametersForLlm` schema (small surface: `command` + `args` as JSON string) and validate with a full schema after merging
+
+## Registering slash commands
+
+Commands are invoked by the user via `/name args`.
+
+```typescript
+api.registerCommand("deploy", {
+  description: "Deploy the application to staging or production",
+  getArgumentCompletions: (prefix) => {
+    const options = [
+      { value: "staging", label: "staging — deploy to staging" },
+      { value: "production", label: "production — deploy to production" },
+    ];
+    const p = prefix.trim().toLowerCase();
+    if (!p) return options;
+    return options.filter((o) => o.value.startsWith(p));
+  },
+  handler: async (args, ctx) => {
+    if (!args.trim()) {
+      ctx.addMessage?.("system", "Usage: /deploy [staging|production]");
+      return;
+    }
+    // ctx.sendMessage sends a user message that triggers an agent response
+    await ctx.sendMessage?.(`Deploy to ${args.trim()}`);
+  },
+});
+```
+
+### ExtensionCommandContext (available in handler)
+
+| Field | Purpose |
+|-------|---------|
+| `cwd` | Current working directory |
+| `addMessage(role, content)` | Add system/error/user message to chat |
+| `sendMessage(text)` | Send as user message (triggers agent response) |
+| `clearMessages()` | Clear conversation |
+| `setModel(id)` | Switch model |
+| `exit()` | Close the CLI |
+| `session` | AgentSession (read-only) |
+| `ui` | `select`, `confirm`, `input`, `notify`, `setStatus` |
+| `showModelPicker()` | Open model picker overlay |
+| `showSettings()` | Open settings overlay |
+| `showMcpManager()` | Open MCP manager overlay |
+| `mcp`, `sessionId` | MCP service and session refs |
+| `waitForIdle()` | Wait until agent finishes current turn |
+
+### Reserved command names
+
+Extensions cannot override these built-in commands:
+
+```
+model, models, clear, compact, exit, quit, help, mcp, settings
+```
+
+## Subscribing to lifecycle hooks
+
+```typescript
+api.on("session_start", async ({ sessionId }) => {
+  console.error("Session started:", sessionId);
+});
+
+api.on("context", async (context) => {
+  // Mutate in place before each LLM call
+  context.systemPrompt += "\n\n## My custom instructions\n...";
+});
+```
+
+### Available hooks
+
+| Hook | Payload | Description |
+|------|---------|-------------|
+| `session_start` | `{ sessionId }` | After session creation |
+| `session_end` | `{ sessionId }` | Session ends |
+| `session_shutdown` | `{}` | Process exit; flush buffers |
+| `before_agent_start` | `{ text, sessionId }` | Before agent loop |
+| `agent_start` / `agent_end` | `{ turnId }` | Agent loop boundaries |
+| `turn_start` / `turn_end` | `{ turnId }` | Per-LLM-turn boundaries |
+| `context` | `{ systemPrompt, messages, tools }` | Mutate before LLM call |
+| `input` | `InputEvent` | Transform user input before send |
+| `tool_call` | `ToolCallEvent` | Intercept/deny tool calls |
+| `tool_result` | `ToolResultEvent` | Modify tool results |
+| `model_select` | — | When `setModel()` is called |
+| `session_before_compact` | — | Before compaction; return `{ cancel: true }` to cancel |
+
+## Tool interception
+
+Block dangerous tool calls or modify results:
+
+```typescript
+api.on("tool_call", async ({ toolName, input }) => {
+  if (toolName === "bash" && input.command?.includes("rm -rf /")) {
+    return { deny: true, reason: "Blocked destructive command" };
+  }
+});
+
+api.on("tool_result", async (event) => {
+  if (event.toolName === "read") {
+    event.content = redactSecrets(event.content);
+  }
+});
+```
+
+## Input transformation
+
+Transform or intercept user messages before they reach the agent:
+
+```typescript
+api.on("input", async ({ text, source }) => {
+  if (text.startsWith("!")) {
+    return { action: "transform", text: `Execute shell command: ${text.slice(1)}` };
+  }
+  return { action: "continue" };
+});
+```
+
+Return values: `{ action: "continue" }` (pass through), `{ action: "transform", text }` (replace), `{ action: "handled" }` (swallow).
+
+## Keyboard shortcuts (CLI only)
+
+```typescript
+api.registerShortcut?.("ctrl+shift+d", {
+  description: "Quick deploy",
+  handler: (ctx) => {
+    ctx.addMessage?.("system", "Deploying...");
+  },
+});
+```
+
+Reserved shortcuts that cannot be overridden:
+
+```
+escape, ctrl+c, ctrl+l, ctrl+o, ctrl+u, ctrl+d, ctrl+j, ctrl+s, ctrl+shift+c
+```
+
+## Provider registration
+
+Register a custom model provider:
+
+```typescript
+api.registerProvider?.("my-llm", {
+  baseUrl: "https://api.example.com",
+  apiKey: process.env.MY_API_KEY,
+  models: [{ id: "my-model", name: "My Model", contextWindow: 128000 }],
+});
+```
+
+Providers are merged into config before session creation.
+
+## Spawning subprocesses (CLI tool pattern)
+
+For tools that wrap external binaries, use `child_process.spawn`:
+
+```typescript
+import { spawn } from "node:child_process";
+
+function runBinary(
+  args: readonly string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("my-binary", args, {
+      cwd,
+      env: process.env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk: string) => { stderr += chunk; });
+    const timer = setTimeout(() => child.kill("SIGTERM"), timeoutMs);
+    child.on("error", (err) => { clearTimeout(timer); reject(err); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode: code ?? -1 });
+    });
+  });
+}
+```
+
+Wire the spawn helper into `execute` and pass `context.signal` for cancellation support.
+
+## Checklist
+
+Before delivering an extension, verify:
+
+- [ ] Exports `activate` or `default` function receiving `ExtensionAPI`
+- [ ] Imports types and `z` from `@globant/coda-core` (not directly from `zod`)
+- [ ] Tool `description` clearly explains when the LLM should use it
+- [ ] Tool `parameters` use Zod with `.describe()` on each field
+- [ ] Tool `execute` returns a string (the LLM reads the return value)
+- [ ] Command names don't collide with reserved built-ins
+- [ ] Shortcut IDs don't collide with reserved shortcuts
+- [ ] Error handling returns user-friendly messages (not raw stack traces)
+- [ ] Subprocess tools respect `context.signal` for cancellation
+- [ ] File placed in `.coda/extensions/` (project) or `~/.coda/extensions/` (global)
+
+## Reference
+
+For the full architecture (hook flow diagrams, desktop integration, runner internals), see the Coda extensions guide shipped with the CLI under `docs/` in the g-coda repository (`docs/core/extensions/extensions.md`).