codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/examples/plugins/web-search.ts

@@ -0,0 +1,324 @@
+/**
+ * Web Search Plugin Example
+ *
+ * Registers a `web_search` tool backed by Exa.
+ *
+ * CLI usage:
+ *   cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/web-search.ts --cwd .
+ *   EXA_API_KEY=... cline "Search the web for recent TypeScript 6 updates"
+ *
+ * Provider key:
+ *   EXA_API_KEY              Enables Exa search. A separate model provider key
+ *                            is still required for CLI inference.
+ */
+
+import { type AgentPlugin, createTool } from "@cline/core";
+
+export interface WebSearchInput {
+	query: string;
+	limit?: number;
+	domains?: string[];
+	recencyDays?: number;
+	country?: string;
+}
+
+export interface WebSearchResult {
+	title: string;
+	url: string;
+	snippet?: string;
+	publishedAt?: string;
+	author?: string;
+	score?: number;
+	source: "exa";
+}
+
+export interface WebSearchOutput {
+	provider: "exa";
+	query: string;
+	results: WebSearchResult[];
+	requestId?: string;
+}
+
+interface ExaSearchResult {
+	title?: string;
+	url?: string;
+	publishedDate?: string;
+	author?: string;
+	score?: number;
+	text?: string;
+	highlights?: string[];
+	summary?: string;
+}
+
+interface ExaSearchResponse {
+	requestId?: string;
+	results?: ExaSearchResult[];
+	error?: string;
+}
+
+const DEFAULT_RESULT_LIMIT = 5;
+const MAX_RESULT_LIMIT = 10;
+const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+
+function env(name: string): string | undefined {
+	const value = process.env[name]?.trim();
+	return value ? value : undefined;
+}
+
+function clampResultLimit(limit: number | undefined): number {
+	if (typeof limit !== "number" || !Number.isFinite(limit)) {
+		return DEFAULT_RESULT_LIMIT;
+	}
+	const integer = Math.trunc(limit);
+	return Math.min(Math.max(integer, 1), MAX_RESULT_LIMIT);
+}
+
+function normalizeDomains(domains: string[] | undefined): string[] | undefined {
+	const normalized = domains
+		?.map((domain) => domain.trim().replace(/^https?:\/\//, ""))
+		.map((domain) => domain.replace(/\/.*$/, ""))
+		.filter(Boolean);
+	return normalized && normalized.length > 0
+		? [...new Set(normalized)]
+		: undefined;
+}
+
+function isoDateDaysAgo(days: number | undefined): string | undefined {
+	if (typeof days !== "number" || !Number.isFinite(days) || days <= 0) {
+		return undefined;
+	}
+	const date = new Date();
+	date.setUTCDate(date.getUTCDate() - Math.trunc(days));
+	return date.toISOString();
+}
+
+function truncateSnippet(text: string | undefined): string | undefined {
+	if (!text) {
+		return undefined;
+	}
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!normalized) {
+		return undefined;
+	}
+	return normalized.length > 800
+		? `${normalized.slice(0, 797).trimEnd()}...`
+		: normalized;
+}
+
+function extractErrorMessage(body: unknown): string | undefined {
+	if (!body || typeof body !== "object") {
+		return undefined;
+	}
+	const record = body as Record<string, unknown>;
+	for (const key of ["error", "message", "detail"] as const) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value)
+		? value
+		: undefined;
+}
+
+function hasResultUrl(
+	result: ExaSearchResult,
+): result is ExaSearchResult & { url: string } {
+	return typeof result.url === "string" && result.url.trim().length > 0;
+}
+
+function parseWebSearchInput(input: unknown): WebSearchInput {
+	if (!input || typeof input !== "object") {
+		throw new Error("web_search input must be an object");
+	}
+	const record = input as Record<string, unknown>;
+	const query = asString(record.query);
+	if (!query) {
+		throw new Error("query is required");
+	}
+
+	const domains = Array.isArray(record.domains)
+		? record.domains.flatMap((domain) => {
+				const value = asString(domain);
+				return value ? [value] : [];
+			})
+		: undefined;
+
+	return {
+		query,
+		limit: asNumber(record.limit),
+		domains,
+		recencyDays: asNumber(record.recencyDays),
+		country: asString(record.country),
+	};
+}
+
+async function readJsonResponse<T>(response: Response): Promise<T> {
+	const text = await response.text();
+	let body: unknown = {};
+	try {
+		body = text ? (JSON.parse(text) as unknown) : {};
+	} catch {
+		if (!response.ok) {
+			throw new Error(
+				`HTTP ${response.status}: ${text || response.statusText}`,
+			);
+		}
+		throw new Error("Search provider returned invalid JSON");
+	}
+
+	if (!response.ok) {
+		const message = extractErrorMessage(body) ?? (text || response.statusText);
+		throw new Error(`HTTP ${response.status}: ${message}`);
+	}
+
+	return body as T;
+}
+
+function resolveExaApiKey(): string {
+	const exaApiKey = env("EXA_API_KEY");
+	if (!exaApiKey) {
+		throw new Error("Set EXA_API_KEY to use web_search");
+	}
+	return exaApiKey;
+}
+
+async function searchExa(
+	input: WebSearchInput,
+	apiKey: string,
+	limit: number,
+	domains: string[] | undefined,
+): Promise<WebSearchOutput> {
+	const body: Record<string, unknown> = {
+		query: input.query,
+		numResults: limit,
+		contents: {
+			highlights: true,
+		},
+	};
+	if (domains) {
+		body.includeDomains = domains;
+	}
+	const startPublishedDate = isoDateDaysAgo(input.recencyDays);
+	if (startPublishedDate) {
+		body.startPublishedDate = startPublishedDate;
+	}
+	if (input.country) {
+		body.userLocation = input.country.toLowerCase();
+	}
+
+	const response = await fetch(EXA_SEARCH_ENDPOINT, {
+		method: "POST",
+		headers: {
+			"x-api-key": apiKey,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify(body),
+	});
+	const json = await readJsonResponse<ExaSearchResponse>(response);
+
+	if (json.error) {
+		throw new Error(json.error);
+	}
+
+	return {
+		provider: "exa",
+		query: input.query,
+		requestId: json.requestId,
+		results: (json.results ?? [])
+			.filter(hasResultUrl)
+			.slice(0, limit)
+			.map((result) => ({
+				title: result.title || result.url || "Untitled",
+				url: result.url,
+				snippet: truncateSnippet(
+					result.highlights?.join("\n") ?? result.summary ?? result.text,
+				),
+				publishedAt: result.publishedDate,
+				author: result.author,
+				score: result.score,
+				source: "exa",
+			})),
+	};
+}
+
+export async function searchWeb(
+	input: WebSearchInput,
+): Promise<WebSearchOutput> {
+	if (!input.query || !input.query.trim()) {
+		throw new Error("query is required");
+	}
+
+	const limit = clampResultLimit(input.limit);
+	const domains = normalizeDomains(input.domains);
+	const apiKey = resolveExaApiKey();
+
+	return searchExa(input, apiKey, limit, domains);
+}
+
+const plugin: AgentPlugin = {
+	name: "web-search",
+	manifest: {
+		capabilities: ["tools"],
+	},
+
+	setup(api) {
+		api.registerTool(
+			createTool({
+				name: "web_search",
+				description:
+					"Search the web for current public information using Exa. " +
+					"Use this to discover relevant URLs, news, docs, and recent facts; use fetch_web_content afterward when a page needs deeper inspection. " +
+					"Requires EXA_API_KEY in the plugin host environment.",
+				inputSchema: {
+					type: "object",
+					properties: {
+						query: {
+							type: "string",
+							description:
+								"Search query. Use precise terms and include dates when recency matters.",
+						},
+						limit: {
+							type: "number",
+							description: `Number of results to return, from 1 to ${MAX_RESULT_LIMIT}. Defaults to ${DEFAULT_RESULT_LIMIT}.`,
+						},
+						domains: {
+							type: "array",
+							items: { type: "string" },
+							description:
+								"Optional domains to restrict results to, such as github.com or docs.exa.ai.",
+						},
+						recencyDays: {
+							type: "number",
+							description:
+								"Optional freshness window in days. Maps to Exa startPublishedDate.",
+						},
+						country: {
+							type: "string",
+							description:
+								"Optional lowercase two-letter country code for localized results, such as us.",
+						},
+					},
+					required: ["query"],
+					additionalProperties: false,
+				},
+				timeoutMs: 30_000,
+				retryable: true,
+				maxRetries: 1,
+				execute: async (input: unknown) =>
+					searchWeb(parseWebSearchInput(input)),
+			}),
+		);
+	},
+};
+
+export { plugin };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/tsconfig.json

@@ -0,0 +1,58 @@
+{
+	"extends": "../../apps/tsconfig.apps.json",
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": ["ESNext"],
+		"types": ["bun"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": false,
+		"noImplicitOverride": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false,
+		"paths": {
+			"@cline/agents": ["../packages/agents/src/index.ts"],
+			"@cline/agents/*": [
+				"../packages/agents/src/*",
+				"../packages/agents/src/*/index.ts"
+			],
+			"@cline/cline-hub": ["./cline-hub/src/server.ts"],
+			"@cline/core": ["../packages/core/src/index.ts"],
+			"@cline/core/hub/daemon-entry": [
+				"../packages/core/src/hub/daemon/entry.ts"
+			],
+			"@cline/core/*": [
+				"../packages/core/src/*",
+				"../packages/core/src/*/index.ts"
+			],
+			"@cline/core/telemetry": [
+				"../packages/core/src/services/telemetry/index.ts"
+			],
+			"@cline/llms": ["../packages/llms/src/index.ts"],
+			"@cline/shared": ["../packages/shared/src/index.ts"],
+			"@cline/shared/storage": ["../packages/shared/src/storage/index.ts"],
+			"@cline/shared/db": ["../packages/shared/src/db/index.ts"],
+			"@cline/shared/*": [
+				"../packages/shared/src/*",
+				"../packages/shared/src/*/index.ts"
+			]
+		}
+	}
+}

codna/agent-core/vendor/cline/sdk/packages/README.md

@@ -0,0 +1,44 @@
+# Packages Overview
+
+This directory is the single documentation source for package-level responsibilities.
+
+- High-level package roles: this file (`packages/README.md`)
+- Package interaction and runtime flows: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+
+## Package Responsibilities
+
+| Package | Primary responsibility | Typical consumers | Internal deps |
+| --- | --- | --- | --- |
+| `@cline/shared` | Cross-package shared primitives (path resolution, session common types, indexing helpers) | `@cline/agents`, `@cline/core`, apps | None |
+| `@cline/llms` | Model catalog + provider settings schema + handler creation SDK | `@cline/agents`, `@cline/core`, apps | None |
+| `@cline/agents` | Stateless agent runtime loop (tools, hooks, extensions, teams, streaming) | `@cline/core`, apps | `@cline/llms`, `@cline/shared` |
+| `@cline/core` | Stateful runtime orchestration (runtime composition, session lifecycle/storage, local and hub runtime services, hub discovery and client helpers) | CLI/Desktop apps | `@cline/agents`, `@cline/llms`, `@cline/shared` |
+
+## How Packages Work Together
+
+1. `@cline/llms` defines model/provider capabilities and builds concrete handlers.
+2. `@cline/agents` runs the agent loop on top of those handlers and tool execution primitives.
+3. `@cline/core` composes runtime behavior with persistent sessions/storage and local or hub-backed runtime services.
+4. `@cline/core` hub services orchestrate scheduled runtime execution, execution history, and schedule command handling.
+5. `@cline/core/hub` exposes discovery, the detached hub daemon, and session-oriented client APIs (`HubSessionClient`, `HubUIClient`) when hosts need a shared daemon.
+6. `@cline/shared` provides the shared contracts and path/session primitives used across the stack.
+
+## Practical Boundary Rules
+
+- Put provider/model schema, cataloging, and handler wiring in `@cline/llms`.
+- Put loop/tool/hook/team execution behavior in `@cline/agents`.
+- Put persistence, session lifecycle, and runtime assembly in `@cline/core`.
+- Put scheduled execution and schedule persistence in `@cline/core` hub services.
+- Put hub discovery, attach flows, and session-oriented client adapters in `@cline/core/hub`.
+- Put cross-package utility types and path/session constants in `@cline/shared`.
+- Put remote-config schemas, materialization, telemetry normalization, and blob upload primitives in `@cline/shared/remote-config`.
+
+## Runtime Entry Points
+
+- Node-oriented imports exist where packages expose a distinct Node alias.
+- `@cline/core` itself is now the Node/runtime-oriented entry point for host/session services.
+- Browser entry points still exist in packages that intentionally publish a browser surface, but `@cline/core` no longer does.
+
+## Notes for Doc Consolidation
+
+Nested package `README.md` and `ARCHITECTURE.md` files can be reduced or removed after references are updated to point here.

codna/agent-core/vendor/cline/sdk/packages/agents/README.md

@@ -0,0 +1,278 @@
+# [experimental] @cline/agents
+
+`@cline/agents` is the runtime-agnostic agent loop package in the Cline SDK.
+It gives you the core primitives for building tool-using LLM agents without
+bringing in session storage, hub transport, or host-specific default tools.
+
+## What You Get
+
+- `Agent` / `AgentRuntime` — the same class under two names — for running and
+  continuing tool-using agent conversations
+- `createAgent` / `createAgentRuntime` — factory-function equivalents
+- `AgentRuntimeHooks` for lifecycle interception (`beforeRun`, `afterRun`,
+  `beforeModel`, `afterModel`, `beforeTool`, `afterTool`, `onEvent`)
+- Event streaming via `agent.subscribe(listener)` and the `hooks.onEvent`
+  callback
+- Plugin setup callbacks for contributing tools and hooks at boot
+
+## What This Package Does Not Include
+
+`@cline/agents` does not ship a full application runtime by itself.
+
+- Default host tools like filesystem access, shell execution, or web fetching live in `@cline/core`
+- Session persistence and stateful orchestration live in `@cline/core`
+- Shared hub runtime/session transport lives in `@cline/core` (see `@cline/core/hub`)
+- Sub-agent and team coordination primitives live in `@cline/core`
+
+That split keeps this package usable in Node, browser, and custom host
+environments where you want to supply your own tools and runtime policy.
+
+## Installation
+
+```bash
+npm install @cline/agents @cline/shared @cline/llms
+```
+
+## Quick Start
+
+```ts
+import { Agent } from "@cline/agents";
+import type { AgentTool } from "@cline/shared";
+
+const getWeather: AgentTool<{ city: string }, { forecast: string }> = {
+	name: "get_weather",
+	description: "Return the current weather for a city.",
+	inputSchema: {
+		type: "object",
+		properties: { city: { type: "string" } },
+		required: ["city"],
+	},
+	async execute({ city }) {
+		return { forecast: `sunny in ${city}` };
+	},
+};
+
+const agent = new Agent({
+	providerId: "anthropic",
+	modelId: "claude-sonnet-4-6",
+	apiKey: process.env.ANTHROPIC_API_KEY,
+	systemPrompt: "You are a concise assistant.",
+	tools: [getWeather],
+});
+
+const result = await agent.run("What's the weather in San Francisco?");
+console.log(result.outputText);
+```
+
+## Two Ways to Configure
+
+`Agent` / `AgentRuntime` accepts two config shapes:
+
+**Provider form** — friendly entrypoint. The runtime builds an `AgentModel` for
+you via `@cline/llms`:
+
+```ts
+new Agent({
+	providerId: "openai",
+	modelId: "gpt-5",
+	apiKey: process.env.OPENAI_API_KEY,
+	// baseUrl, headers also supported
+	tools: [/* ... */],
+});
+```
+
+**Model form** — advanced. Supply a pre-built `AgentModel` directly. Useful
+when the host already owns gateway construction (this is what `@cline/core`
+uses internally):
+
+```ts
+import { createGateway } from "@cline/llms";
+
+const gateway = createGateway({ providerConfigs: [/* ... */] });
+const model = gateway.createAgentModel({ providerId, modelId });
+
+new Agent({
+	model,
+	tools: [/* ... */],
+});
+```
+
+## Core Concepts
+
+### Tools
+
+Tools conform to the `AgentTool<TInput, TOutput>` interface from
+`@cline/shared`. Each tool has a JSON Schema `inputSchema` and an
+`execute(input, context)` function that returns the tool output directly:
+
+```ts
+import type { AgentTool } from "@cline/shared";
+
+const summarize: AgentTool<{ text: string }, { summary: string }> = {
+	name: "summarize_text",
+	description: "Summarize text into a short preview.",
+	inputSchema: {
+		type: "object",
+		properties: { text: { type: "string" } },
+		required: ["text"],
+	},
+	async execute({ text }, context) {
+		// context.signal — aborts when the run is cancelled
+		// context.emitUpdate(...) — stream progress as `tool-updated` events
+		return { summary: text.slice(0, 120) };
+	},
+};
+```
+
+The runtime wraps successful tool outputs in an internal tool-result message.
+Throw from `execute(...)` to report a tool failure, or use an `afterTool` hook
+to transform the internal `AgentToolResult` envelope.
+
+### Events
+
+Subscribe to the `AgentRuntimeEvent` stream in one of two ways:
+
+```ts
+// 1. Attach a listener after construction. Returns an unsubscribe function.
+const unsubscribe = agent.subscribe((event) => {
+	if (event.type === "assistant-text-delta") {
+		process.stdout.write(event.text);
+	}
+});
+
+// 2. Register an `onEvent` hook at construction time.
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	hooks: {
+		onEvent(event) {
+			// fires for every runtime event
+		},
+	},
+});
+```
+
+`AgentRuntimeEvent` covers run/turn boundaries, assistant text and reasoning
+deltas, tool lifecycle, usage updates, and run completion/failure. See
+`AgentRuntimeEvent` in `@cline/shared` for the full union.
+
+### Conversation Control
+
+- `agent.run(input)` — start a run. `input` may be a string, an `AgentMessage`,
+  or an array of messages. Also accepts `undefined` to continue without adding
+  a new user turn.
+- `agent.continue(input?)` — convenience alias for `run(input?)`.
+- `agent.abort(reason?)` — cancel the active run. `.run()` resolves with
+  `status: "aborted"`.
+- `agent.snapshot()` — immutable view of the current
+  `AgentRuntimeStateSnapshot` (messages, usage, iteration, status, etc.).
+- `agent.restore(messages)` — replace the conversation with a persisted
+  message array. Resets run/turn state but preserves subscribers, tools,
+  hooks, plugins, and the model.
+- `initialMessages` in the constructor seeds the conversation on boot.
+
+### Hooks
+
+Pass a `hooks` bag (`AgentRuntimeHooks`) to observe or influence the loop.
+All hooks may be async; any that return `{ stop: true, reason }` will halt the
+run with an `aborted` status.
+
+```ts
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	tools: [/* ... */],
+	hooks: {
+		beforeModel({ request }) {
+			// mutate messages/tools/options before the model call
+			return { options: { temperature: 0.2 } };
+		},
+		beforeTool({ tool, input }) {
+			// block a tool call based on policy
+			if (tool.name === "get_weather" && !(input as { city?: string }).city) {
+				return { skip: true, reason: "city required" };
+			}
+			return undefined;
+		},
+		afterRun({ result }) {
+			console.log("done", result.usage);
+		},
+	},
+});
+```
+
+For richer, host-side hook orchestration (15-stage `HookEngine`,
+subprocess-backed hooks, MCP extensions), use `@cline/core`.
+
+### Plugins
+
+Plugins can contribute tools and hooks at setup time:
+
+```ts
+import type { AgentRuntimePlugin } from "@cline/shared";
+
+const loggingPlugin: AgentRuntimePlugin = {
+	name: "logging",
+	setup({ agentId }) {
+		return {
+			hooks: {
+				afterTool({ tool, result }) {
+					console.log(agentId, tool.name, result.isError);
+					return undefined; // hook may return an AgentAfterToolResult
+				},
+			},
+		};
+	},
+};
+
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	plugins: [loggingPlugin],
+});
+```
+
+### Teams and Spawn
+
+For multi-agent workflows, use `@cline/core`:
+
+```ts
+import {
+	createSpawnAgentTool,
+	AgentTeamsRuntime,
+	createAgentTeamsTools,
+	bootstrapAgentTeams,
+} from "@cline/core";
+```
+
+These helpers provide coordination primitives for delegated runs,
+mailboxes, task management, and outcome convergence.
+
+## Entry Point
+
+- `@cline/agents` — the single package entrypoint. The `package.json`
+  `exports` map automatically serves a browser-safe bundle when bundlers
+  resolve the `browser` condition.
+
+## Related Packages
+
+- `@cline/shared`: shared types (`AgentTool`, `AgentMessage`,
+  `AgentRuntimeEvent`, `AgentRuntimeHooks`, etc.)
+- `@cline/llms`: provider settings, model catalogs, and gateway/handler
+  creation
+- `@cline/core`: stateful runtime assembly, storage, default tools,
+  subprocess hooks, hub transport, and MCP integration
+
+## More Examples
+
+- Repo examples:
+  [examples/plugins](https://github.com/cline/sdk/tree/main/examples/plugins),
+  [examples/hooks](https://github.com/cline/sdk/tree/main/examples/hooks),
+  [examples/cron](https://github.com/cline/sdk/tree/main/examples/cron)
+- Workspace overview: [README.md](https://github.com/cline/sdk/blob/main/README.md)
+- API and architecture references:
+  [DOC.md](https://github.com/cline/sdk/blob/main/DOC.md),
+  [ARCHITECTURE.md](https://github.com/cline/sdk/blob/main/ARCHITECTURE.md)