@theokit/sdk 4.53.0 → 4.54.0

package/claude-template/dot-claude/skills/theokit-cron/SKILL.md

@@ -1,148 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*cron*"
-  - "**/*Cron*"
-  - "**/*job*"
-  - "**/*schedule*"
-description: TheoKit SDK Cron jobs API reference — Cron.create, schedule syntax, job lifecycle
----
-
-# TheoKit Cron Jobs
-
-Schedule Theo agent runs on a cron expression. Two runtimes mirror the agent
-split: local (in-process scheduler) and cloud (Theo PaaS, pre-release).
-
-## Creating a job
-
-```typescript
-import { Cron } from "@theokit/sdk";
-
-const job = await Cron.create({
-  cron: "0 9 * * *",                 // every day at 09:00
-  timezone: "America/Sao_Paulo",
-  message: "Summarize yesterday's commits and post to #engineering",
-  agent: {
-    apiKey: process.env.THEOKIT_API_KEY!,
-    model: { id: "google/gemini-2.0-flash-001" },
-    local: { cwd: process.cwd() },
-  },
-});
-
-await Cron.start();  // required for local jobs to fire
-```
-
-## Agent binding
-
-Pass exactly one of:
-
-- **`agent`** (full `AgentOptions`) — a fresh agent is created on every fire.
-  Use for independent runs.
-- **`agentId`** (string) — reuses an existing agent's conversation context
-  across fires. Use for continuity (e.g., weekly review building on past notes).
-
-Setting both raises `ConfigurationError`.
-
-## Cron expressions
-
-| Format | Example | Meaning |
-|---|---|---|
-| 5-field POSIX | `0 9 * * *` | Minute, hour, day-of-month, month, day-of-week |
-| `@hourly` | `@hourly` | Every hour at minute 0 |
-| `@daily` | `@daily` | Every day at midnight |
-| `@weekly` | `@weekly` | Every Sunday at midnight |
-| `@monthly` | `@monthly` | First day of month at midnight |
-| `@yearly` | `@yearly` | January 1 at midnight |
-
-`timezone` accepts any IANA identifier (default: `"UTC"`). Invalid expressions
-throw `ConfigurationError` synchronously at create time.
-
-## Managing jobs
-
-```typescript
-const { items } = await Cron.list({ runtime: "local", cwd: process.cwd() });
-const job = await Cron.get(jobId);
-
-await Cron.disable(jobId);   // pause without deleting
-await Cron.enable(jobId);    // resume
-await Cron.delete(jobId);    // permanent removal
-```
-
-## Manual fire (off-schedule)
-
-```typescript
-const run = await Cron.run(jobId);
-
-for await (const event of run.stream()) {
-  // same SDKMessage events as any other run
-}
-```
-
-Manual fires do not update `lastRunAt` — only scheduled fires do.
-
-## Local scheduler lifecycle
-
-```typescript
-await Cron.start({ cwd: process.cwd() });  // reads .theokit/cron/jobs.json
-const status = await Cron.status();
-// { running: true, jobCount: 3, nextFireAt: 1747... }
-await Cron.stop();  // halts scheduling; does NOT delete jobs
-```
-
-Local jobs only fire while the host process is alive. Run as `pm2` / `systemd`
-service for 24/7 local scheduling.
-
-## Persistence
-
-Local cron state lives in `.theokit/cron/jobs.json`. Created automatically by
-`Cron.create()`. Commit it if jobs should travel with the repo; add to
-`.gitignore` if environment-specific.
-
-## Type reference
-
-```typescript
-interface CronJob {
-  id: string;
-  name?: string;
-  cron: string;
-  timezone?: string;
-  message: string | SDKUserMessage;
-  agent?: AgentOptions;              // mutually exclusive with agentId
-  agentId?: string;
-  enabled: boolean;
-  status: "scheduled" | "running" | "paused" | "errored";
-  runtime: "local" | "cloud";
-  lastRunAt?: number;
-  nextRunAt?: number;
-  createdAt: number;
-}
-
-interface CronCreateOptions {
-  cron: string;
-  message: string | SDKUserMessage;
-  agent?: AgentOptions;
-  agentId?: string;
-  name?: string;
-  timezone?: string;
-  enabled?: boolean;                 // defaults to true
-  apiKey?: string;
-}
-
-interface CronSchedulerStatus {
-  running: boolean;
-  jobCount: number;
-  nextFireAt?: number;
-  lastError?: { jobId: string; message: string; at: number };
-}
-```
-
-## Cloud jobs (pre-release)
-
-Cloud jobs use Theo PaaS and do not need `Cron.start()`. Pass `agent.cloud`
-to create a cloud-scheduled job. Pre-release — not yet GA.
-
-## Known limitations
-
-- Local jobs only fire while the host process is alive.
-- In-flight fires are not resumed if the host process crashes mid-run.
-- `Cron.run()` (manual fire) does not update `lastRunAt`.

package/claude-template/dot-claude/skills/theokit-di/SKILL.md

@@ -1,233 +0,0 @@
----
-user-invocable: false
-description: Dependency injection container, decorators, scopes, and modules for @theokit/di.
-paths:
-  - "**/*container*"
-  - "**/*inject*"
-  - "**/*provider*"
-  - "**/*module*"
----
-
-# TheoKit DI -- Dependency Injection
-
-Quick reference for `@theokit/di` -- a TypeScript DI container with decorator metadata.
-
-## Installation
-
-```bash
-pnpm add @theokit/di reflect-metadata
-```
-
-Requires `reflect-metadata` polyfill imported once at app entry and `experimentalDecorators` + `emitDecoratorMetadata` in `tsconfig.json`.
-
-## Core decorators
-
-### @Injectable
-
-```typescript
-import { Injectable, Scope } from "@theokit/di";
-
-@Injectable()
-class UserRepository {
-  findById(id: string) { /* ... */ }
-}
-
-// With options:
-@Injectable({ scope: Scope.REQUEST })
-class RequestScopedService { /* ... */ }
-```
-
-`InjectableOptions`:
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `scope` | `Scope` | `Scope.SINGLETON` | Lifecycle scope. |
-
-### @Inject
-
-```typescript
-import { Inject } from "@theokit/di";
-
-@Injectable()
-class OrderService {
-  constructor(
-    @Inject("DATABASE_URL") private readonly dbUrl: string,
-    private readonly repo: UserRepository, // auto-resolved by type
-  ) {}
-}
-```
-
-Use `@Inject(token)` for string/symbol tokens. Constructor parameter types are auto-resolved via `reflect-metadata` when the parameter is a class.
-
-### @Optional
-
-```typescript
-import { Optional } from "@theokit/di";
-
-@Injectable()
-class NotificationService {
-  constructor(
-    @Optional() private readonly sms?: SmsGateway,
-  ) {}
-}
-```
-
-Resolves to `undefined` instead of throwing `TokenNotFoundError` when the dependency is not registered.
-
-### @Qualifier
-
-```typescript
-import { Qualifier } from "@theokit/di";
-
-@Injectable()
-class PaymentService {
-  constructor(
-    @Qualifier("stripe") private readonly gateway: PaymentGateway,
-  ) {}
-}
-```
-
-Disambiguates between multiple providers registered under the same interface token.
-
-### @Primary
-
-```typescript
-import { Primary, Injectable } from "@theokit/di";
-
-@Injectable()
-@Primary()
-class StripeGateway implements PaymentGateway { /* ... */ }
-```
-
-Marks a provider as the default when multiple are registered for the same token. Wins over non-primary providers unless `@Qualifier` is used.
-
-### @PostConstruct / @PreDestroy
-
-```typescript
-import { PostConstruct, PreDestroy, Injectable } from "@theokit/di";
-
-@Injectable()
-class DatabasePool {
-  @PostConstruct()
-  async init() { /* called after construction */ }
-
-  @PreDestroy()
-  async shutdown() { /* called on container.dispose() */ }
-}
-```
-
-## Container
-
-```typescript
-import { Container } from "@theokit/di";
-
-const container = new Container();
-
-// Register classes
-container.register(UserRepository);
-container.register(OrderService);
-
-// Register value providers
-container.register("DATABASE_URL", { useValue: "postgres://..." });
-
-// Register factory providers
-container.register("Logger", {
-  useFactory: (ctx) => new Logger(ctx.resolve("DATABASE_URL")),
-});
-
-// Register existing (alias)
-container.register("PrimaryRepo", { useExisting: UserRepository });
-
-// Resolve
-const service = container.resolve(OrderService);
-const asyncService = await container.resolveAsync(OrderService);
-
-// Dispose (calls @PreDestroy hooks)
-await container.dispose();
-```
-
-### ContainerOptions
-
-```typescript
-interface ContainerOptions {
-  parent?: Container;    // hierarchical containers
-  autoRegister?: boolean; // default false
-}
-```
-
-### Provider types
-
-```typescript
-type Provider =
-  | ClassProvider      // { useClass: Constructor, scope? }
-  | ValueProvider      // { useValue: any }
-  | FactoryProvider    // { useFactory: (ctx) => any, scope? }
-  | ExistingProvider;  // { useExisting: Token }
-```
-
-## Scopes
-
-```typescript
-import { Scope } from "@theokit/di";
-```
-
-| Scope | Behavior |
-|---|---|
-| `Scope.SINGLETON` | One instance per container (default). |
-| `Scope.TRANSIENT` | New instance on every resolve. |
-| `Scope.REQUEST` | One instance per request scope (via `container.createScope()`). |
-
-Request scope example:
-
-```typescript
-const requestContainer = container.createScope();
-const handler = requestContainer.resolve(RequestHandler);
-// All REQUEST-scoped deps share the same instance within this scope
-```
-
-## @Module
-
-```typescript
-import { Module } from "@theokit/di";
-
-@Module({
-  providers: [UserRepository, OrderService],
-  imports: [DatabaseModule],
-  exports: [UserRepository],
-})
-class UserModule {}
-
-// Load module into container
-container.loadModule(UserModule);
-```
-
-`ModuleMetadata`:
-
-| Field | Type | Description |
-|---|---|---|
-| `providers` | `Provider[]` | Classes/providers registered in this module. |
-| `imports` | `Module[]` | Other modules whose exports become available. |
-| `exports` | `Token[]` | Tokens visible to importing modules. |
-
-## Errors
-
-| Error | Cause |
-|---|---|
-| `TokenNotFoundError` | Token not registered and not `@Optional`. |
-| `CyclicDependencyError` | Circular dependency detected in resolution graph. |
-| `MissingInjectableError` | Class used as dependency without `@Injectable`. |
-| `ScopeViolationError` | Singleton depends on transient/request-scoped dep. |
-| `ContainerDisposedError` | Resolve called after `container.dispose()`. |
-| `ContainerFrozenError` | Register called after container is frozen. |
-| `AsyncProviderInSyncResolveError` | Async factory used with `resolve()` instead of `resolveAsync()`. |
-| `ReflectMetadataMissingError` | `reflect-metadata` polyfill not imported. |
-| `CyclicModuleImportError` | Circular module imports detected. |
-| `InvalidModuleError` | Module class missing `@Module` decorator. |
-| `InvalidExportError` | Module exports a token not in its providers. |
-
-## Graph analysis
-
-```typescript
-const graph: DependencyGraph = container.analyzeGraph();
-// Useful for debugging dependency chains and detecting issues
-```

package/claude-template/dot-claude/skills/theokit-di-agent/SKILL.md

@@ -1,294 +0,0 @@
----
-user-invocable: false
-description: All 15 agentic decorators from @theokit/di-agent for tools, workflows, evals, cron, and more.
-paths:
-  - "**/*decorator*"
-  - "**/*Decorator*"
-  - "**/di-agent*"
----
-
-# TheoKit DI-Agent -- Agentic Decorators
-
-Quick reference for `@theokit/di-agent` -- 15 decorators that wire agentic capabilities into DI-managed classes.
-
-## Installation
-
-```bash
-pnpm add @theokit/di-agent @theokit/di @theokit/sdk
-```
-
-Requires `reflect-metadata` and TypeScript decorator support (see `@theokit/di` docs).
-
-## createAgentProvider
-
-Bridges `@theokit/di` container with `@theokit/sdk` Agent. Reads decorator metadata from all registered classes and wires tools, workflows, evals, cron jobs, etc.
-
-```typescript
-import { Container } from "@theokit/di";
-import { createAgentProvider } from "@theokit/di-agent";
-
-const container = new Container();
-container.register(MyToolService);
-container.register(MyWorkflowService);
-
-const { agent, dispose } = await createAgentProvider(container, {
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-});
-```
-
-## @Tool
-
-Registers a method as a custom tool exposed to the LLM.
-
-```typescript
-import { Injectable } from "@theokit/di";
-import { Tool } from "@theokit/di-agent";
-import { z } from "zod";
-
-@Injectable()
-class MathService {
-  @Tool({
-    name: "calculate",
-    description: "Evaluate a math expression.",
-    inputSchema: z.object({ expression: z.string() }),
-  })
-  calculate(input: { expression: string }): string {
-    return String(eval(input.expression));
-  }
-}
-```
-
-## @Workflow
-
-Marks a method as a workflow step definition.
-
-```typescript
-import { Workflow } from "@theokit/di-agent";
-
-@Injectable()
-class PipelineService {
-  @Workflow({ name: "data-pipeline", description: "ETL workflow." })
-  async run(input: { source: string }) {
-    // workflow implementation
-  }
-}
-```
-
-## @EvalDecorator
-
-Registers an eval suite on a method.
-
-```typescript
-import { EvalDecorator } from "@theokit/di-agent";
-
-@Injectable()
-class QAService {
-  @EvalDecorator({
-    name: "qa-smoke",
-    dataset: [{ input: "Say ok.", expected: "ok" }],
-  })
-  async evaluate() { /* ... */ }
-}
-```
-
-## @Cron
-
-Registers a cron-scheduled agent task.
-
-```typescript
-import { Cron } from "@theokit/di-agent";
-
-@Injectable()
-class ReportService {
-  @Cron({
-    expression: "0 9 * * *",
-    timezone: "America/Sao_Paulo",
-    message: "Summarize yesterday's commits.",
-  })
-  async dailyReport() { /* ... */ }
-}
-```
-
-## @Subscription
-
-Marks a method as a real-time subscription handler.
-
-```typescript
-import { Subscription } from "@theokit/di-agent";
-
-@Injectable()
-class EventService {
-  @Subscription({ topic: "orders.created", description: "Handle new orders." })
-  async onOrder(event: unknown) { /* ... */ }
-}
-```
-
-## @Auth
-
-Registers authentication/authorization logic for agent operations.
-
-```typescript
-import { Auth } from "@theokit/di-agent";
-
-@Injectable()
-class SecurityService {
-  @Auth({ strategy: "bearer", description: "JWT validation." })
-  async validate(token: string): Promise<boolean> { /* ... */ }
-}
-```
-
-## @Retriever
-
-Registers a retrieval method for RAG pipelines.
-
-```typescript
-import { Retriever } from "@theokit/di-agent";
-
-@Injectable()
-class SearchService {
-  @Retriever({ name: "docs-search", description: "Search documentation." })
-  async search(query: string) { /* ... */ }
-}
-```
-
-## @Reranker
-
-Registers a reranking method for RAG pipelines.
-
-```typescript
-import { Reranker } from "@theokit/di-agent";
-
-@Injectable()
-class RankService {
-  @Reranker({ name: "cohere-reranker", model: "rerank-v3.5" })
-  async rerank(query: string, docs: unknown[]) { /* ... */ }
-}
-```
-
-## @TextSplitter
-
-Registers a text splitting strategy.
-
-```typescript
-import { TextSplitter } from "@theokit/di-agent";
-
-@Injectable()
-class SplitterService {
-  @TextSplitter({ strategy: "recursive", chunkSize: 1000, overlap: 100 })
-  split(text: string) { /* ... */ }
-}
-```
-
-## @UseSandbox
-
-Marks a class or method for sandboxed execution.
-
-```typescript
-import { UseSandbox } from "@theokit/di-agent";
-
-@Injectable()
-class CodeRunner {
-  @UseSandbox({ enabled: true })
-  async execute(code: string) { /* ... */ }
-}
-```
-
-## @SubAgent
-
-Declares a subagent definition on a method.
-
-```typescript
-import { SubAgent } from "@theokit/di-agent";
-
-@Injectable()
-class AgentOrchestrator {
-  @SubAgent({
-    name: "code-reviewer",
-    description: "Expert code reviewer.",
-    prompt: "Review for bugs and security issues.",
-  })
-  async review() { /* ... */ }
-}
-```
-
-## @Hitl (Human-in-the-Loop)
-
-Marks a method as requiring human approval before proceeding.
-
-```typescript
-import { Hitl } from "@theokit/di-agent";
-
-@Injectable()
-class ApprovalService {
-  @Hitl({ description: "Requires manager approval.", timeout: 3600_000 })
-  async approve(request: unknown) { /* ... */ }
-}
-```
-
-## @AutoSummarize
-
-Enables automatic conversation summarization.
-
-```typescript
-import { AutoSummarize } from "@theokit/di-agent";
-
-@Injectable()
-class ChatService {
-  @AutoSummarize({ maxTurns: 20, strategy: "rolling" })
-  async chat() { /* ... */ }
-}
-```
-
-## @InjectAgent
-
-Injects the current `SDKAgent` instance into a class.
-
-```typescript
-import { Injectable } from "@theokit/di";
-import { InjectAgent } from "@theokit/di-agent";
-import type { SDKAgent } from "@theokit/sdk";
-
-@Injectable()
-class AgentAwareService {
-  constructor(@InjectAgent() private readonly agent: SDKAgent) {}
-
-  async doWork() {
-    const run = await this.agent.send("Do something");
-    await run.wait();
-  }
-}
-```
-
-## @MemoryScopeDecorator
-
-Configures memory scope for a class.
-
-```typescript
-import { MemoryScopeDecorator } from "@theokit/di-agent";
-
-@Injectable()
-@MemoryScopeDecorator({ namespace: "billing", scope: "user" })
-class BillingService { /* ... */ }
-```
-
-## Reading metadata (for framework authors)
-
-Each decorator has a companion reader function:
-
-```typescript
-import { readToolMetadata } from "@theokit/di-agent";
-import { readWorkflowMetadata } from "@theokit/di-agent";
-import { readCronMetadata } from "@theokit/di-agent";
-// ... readEvalDecoratorMetadata, readRetrieverMetadata, etc.
-
-const tools = readToolMetadata(MyToolService);
-```
-
-## AGENT_TOKEN
-
-```typescript
-import { AGENT_TOKEN } from "@theokit/di-agent";
-// Symbol token for agent injection in the DI container
-```