@lakitu/sdk 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <img src="assets/laki2-banner.jpeg" alt="Lakitu Banner" width="100%">
+</p>
+
+# Lakitu
+
+> AI agent runtime using **code execution**, not JSON tool calls.
+
+Lakitu is an autonomous development environment that runs in an [E2B](https://e2b.dev) sandbox. The agent writes TypeScript code that imports from **KSAs** (Knowledge, Skills, and Abilities), which gets executed in the sandbox.
+
+## The Code Execution Model
+
+```
+Traditional Agent:          Lakitu Agent:
+┌─────────────────┐         ┌─────────────────┐
+│  LLM Response   │         │  LLM Response   │
+│  {              │         │  ```typescript  │
+│    "tool": "x", │   vs    │  import { x }   │
+│    "args": {}   │         │  await x(...)   │
+│  }              │         │  ```            │
+└────────┬────────┘         └────────┬────────┘
+         │                           │
+    Parse JSON               Execute TypeScript
+    Route to tool            (E2B sandbox)
+         │                           │
+    ┌────▼────┐              ┌───────▼───────┐
+    │ Executor │              │  KSA Modules  │
+    └─────────┘              └───────────────┘
+```
+
+**Why?** Token efficiency (no tool schemas), composability (chain operations in code), debuggability (read exactly what ran).
+
+## KSAs (Knowledge, Skills, and Abilities)
+
+KSAs are TypeScript modules the agent imports. They combine:
+- **Knowledge**: JSDoc documentation
+- **Skills**: Executable functions
+- **Abilities**: What the agent can accomplish
+
+### Available KSAs
+
+| Category | KSA | Functions |
+|----------|-----|-----------|
+| **System** | `file` | `read`, `write`, `edit`, `glob`, `grep`, `ls` |
+| | `browser` | `open`, `screenshot`, `click`, `type`, `getText` |
+| | `beads` | `create`, `update`, `close`, `list`, `getReady` |
+| | `pdf` | `generate` |
+| **Research** | `web` | `search`, `scrape`, `news` |
+| | `news` | `trending`, `monitorBrand`, `analyzeSentiment` |
+| | `social` | `tiktokProfile`, `instagramPosts`, `twitterPosts`, `searchSocial` |
+| **Data** | `companies` | `enrichDomain`, `searchCompanies`, `getTechStack` |
+| **Create** | `email` | `send`, `sendText`, `sendWithAttachment` |
+
+### Example Agent Code
+
+```typescript
+import { search, scrape } from './ksa/web';
+import { enrichDomain } from './ksa/companies';
+import { send } from './ksa/email';
+
+// Research a company
+const results = await search('Stripe payments company');
+const content = await scrape(results[0].url);
+
+// Enrich with company data
+const company = await enrichDomain('stripe.com');
+console.log(`${company.name}: ${company.industry}, ${company.employeeRange} employees`);
+
+// Send findings
+await send({
+  to: 'user@example.com',
+  subject: 'Company Research: Stripe',
+  text: `Industry: ${company.industry}\nEmployees: ${company.employeeRange}`
+});
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              E2B SANDBOX                                 │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                         KSA MODULES                              │    │
+│  │  /home/user/ksa/                                                 │    │
+│  │  ┌──────┐ ┌──────┐ ┌───────┐ ┌─────────┐ ┌───────┐ ┌─────────┐ │    │
+│  │  │ file │ │ web  │ │ news  │ │ social  │ │ email │ │companies│ │    │
+│  │  └──────┘ └──────┘ └───────┘ └─────────┘ └───────┘ └─────────┘ │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                          Local ops │ Gateway calls                       │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                      CLOUD GATEWAY                               │    │
+│  │  HTTP → Convex Services (OpenRouter, APITube, ScrapeCreators)   │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │  /home/user/workspace/    Working files                          │    │
+│  │  /home/user/artifacts/    Persistent outputs (PDFs, screenshots) │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+lakitu/
+├── ksa/                    # KSA modules (agent imports these)
+│   ├── _shared/            # Shared utilities
+│   │   └── gateway.ts      # Cloud gateway client
+│   ├── _templates/         # Templates for new KSAs
+│   ├── web.ts              # Web search & scraping
+│   ├── news.ts             # News research & monitoring
+│   ├── social.ts           # Social media scraping
+│   ├── companies.ts        # Company data enrichment
+│   ├── email.ts            # Email sending
+│   ├── file.ts             # File operations
+│   ├── browser.ts          # Browser automation
+│   ├── beads.ts            # Task tracking
+│   ├── pdf.ts              # PDF generation
+│   └── index.ts            # Discovery & exports
+│
+├── convex/                 # Convex backend
+│   ├── agent/              # Agent loop implementation
+│   │   └── codeExecLoop.ts # Code execution loop (no tool schemas)
+│   ├── actions/            # Convex actions
+│   │   └── codeExec.ts     # Code execution runtime
+│   ├── prompts/            # System prompts
+│   │   └── codeExec.ts     # KSA documentation for agent
+│   └── tools/              # LEGACY: Being removed
+│
+├── shared/                 # Shared types
+│   └── chain-of-thought.ts # Execution tracing
+│
+└── runtime/                # CLI commands for bash
+```
+
+## Adding New KSAs
+
+See `ksa/README.md` for detailed instructions. Quick steps:
+
+1. Copy template from `ksa/_templates/`
+2. Implement functions (use `callGateway()` for external services)
+3. Add to `ksa/index.ts` registry
+4. Document in system prompt (`convex/prompts/codeExec.ts`)
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun dev` | Start local Convex dev server |
+| `bun deploy` | Deploy to Convex cloud |
+| `bun test` | Run unit tests |
+| `bun typecheck` | TypeScript type check |
+
+## Related Documentation
+
+- `CLAUDE.md` - Instructions for AI agents working on this codebase
+- `ksa/README.md` - KSA documentation and extension guide
+- `convex/prompts/codeExec.ts` - System prompt with KSA examples
+
+## Links
+
+- [E2B Documentation](https://e2b.dev/docs)
+- [Convex Documentation](https://docs.convex.dev)

package/convex/_generated/api.d.ts

@@ -0,0 +1,45 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

package/convex/_generated/dataModel.d.ts

@@ -0,0 +1,58 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { AnyDataModel } from "convex/server";
+import type { GenericId } from "convex/values";
+
+/**
+ * No `schema.ts` file found!
+ *
+ * This generated code has permissive types like `Doc = any` because
+ * Convex doesn't know your schema. If you'd like more type safety, see
+ * https://docs.convex.dev/using/schemas for instructions on how to add a
+ * schema file.
+ *
+ * After you change a schema, rerun codegen with `npx convex dev`.
+ */
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = string;
+
+/**
+ * The type of a document stored in Convex.
+ */
+export type Doc = any;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ */
+export type Id<TableName extends TableNames = TableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = AnyDataModel;

package/convex/_generated/server.d.ts

@@ -0,0 +1,143 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/convex/_generated/server.js

@@ -0,0 +1,93 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction = httpActionGeneric;