codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Contributing to the Cline SDK
+
+This document covers onboarding, development workflow, and publishing. For package boundaries and change routing during development, see [AGENTS.md](./AGENTS.md). For architecture and runtime flows, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+This repo is a WIP framework for building and orchestrating AI agents. Full refactors are acceptable when they improve the architecture and all call sites are updated.
+
+## Workspace Overview
+
+### Published SDK Packages
+
+| Package | Owns |
+|---------|------|
+| `@cline/shared` | Contracts, schemas, path helpers, hook engine, extension registry |
+| `@cline/llms` | Provider settings, model catalogs, manifests, handler creation |
+| `@cline/agents` | Stateless agent loop, tool orchestration, hook/extension runtime |
+| `@cline/core` | Stateful orchestration, session lifecycle, storage, config, telemetry, hub runtime services, hub discovery, detached daemon, and hub client adapters (`@cline/core/hub`, `@cline/core/hub/daemon-entry`) |
+
+### Apps
+
+- `apps/cli`: CLI host and local hub management
+- `apps/examples/desktop-app`: Tauri + Next.js desktop app example
+- `apps/examples/vscode`: VS Code extension example
+- `apps/examples/menubar`: hub notification menubar example
+- `examples`: plugin, hook, and cron automation examples (customizations upon Cline SDK)
+
+## Development Workflow
+
+### Essential Commands
+
+| Command | Purpose |
+|---------|---------|
+| `bun install` | Install dependencies |
+| `bun run build` | Build SDK and CLI |
+| `bun run build:sdk` | Build SDK packages only |
+| `bun run dev` | Build in development mode |
+| `bun run cli` | Run CLI interactively |
+| `bun run test` | Run the Vitest suite |
+| `bun run types` | Typecheck all packages |
+| `bun run lint` / `format` / `fix` | Code quality and formatting |
+
+Package-scoped commands:
+
+```sh
+bun -F @cline/core build|test|typecheck
+bun -F @cline/agents build|test|typecheck
+```
+
+### Rebuilding
+
+Changes to published SDK packages require `bun run build:sdk`. Direct CLI runs pick up rebuilt packages immediately. Use `dev:*` scripts for automatic rebuilding during development.
+
+The CLI build (`bun -F @cline/cli build`) bundles packages from their compiled `dist/`, not their TypeScript source. If you edit a package and then build the CLI without rebuilding the package first, the CLI binary will silently include the old package code. Always run `bun run build:sdk` (or the relevant `bun -F @cline/<pkg> build`) before building the CLI when testing changes end-to-end.
+
+Hub-backed hosts use shared workspace discovery and owned daemon startup logic. If you touch hub bootstrap, preserve the startup lock and owner-scoped discovery behavior so multiple builds can coexist safely.
+
+### Debug Builds
+
+- Set `CLINE_BUILD_ENV=development` for debug builds. Spawned Node/Bun subprocesses get an inspector endpoint plus `--enable-source-maps`.
+- By default, child-process inspector ports are ephemeral (`--inspect=127.0.0.1:0`) to avoid collisions across parallel dev runs.
+- Set `CLINE_DEBUG_HOST` and `CLINE_DEBUG_PORT_BASE` to opt into deterministic role-based ports. With `CLINE_DEBUG_PORT_BASE=9230`, the roles map to hub `9230`, hook worker `9231`, plugin sandbox `9232`, connector child `9233`, fallback sandbox `9234`.
+- Fallback chain: `CLINE_BUILD_ENV` → `NODE_ENV` → Bun `--conditions=development`.
+- To debug the CLI process itself: `cd apps/cli && CLINE_BUILD_ENV=development bun --conditions=development --inspect-brk=6499 ./src/index.ts "hey"`.
+- The workspace includes a VS Code launch config (`Launch CLI Debugger`) that uses `"type": "bun"` (requires `oven.bun-vscode`).
+
+### Testing
+
+Root commands for cross-package confidence:
+
+```sh
+bun run test        # all tests
+bun run types       # typecheck all packages
+bun run check       # lint + build + typecheck + check-publish
+```
+
+If you touch hub/bootstrap/session flows, prefer both unit coverage and an end-to-end sanity check.
+
+## Publishing
+
+### SDK Release
+
+The `bun release sdk` script automates the SDK publish flow: versioning, lockfile regeneration, verification, and publishing.
+
+```sh
+bun release sdk              # auto-increment patch version
+bun release sdk 0.1.0        # explicit version
+bun release sdk --tag next   # publish with a custom npm dist-tag
+bun release sdk --dry-run    # preview without side effects
+```
+
+Additional SDK flags: `--skip-tests`, `--skip-git-tags`.
+
+The script checks out `main` (and pulls latest) before starting. If the working tree is dirty it aborts.
+
+The SDK flow runs: tests → version bump → lockfile regeneration → tarball verification → publish (shared → llms → agents → core) → optional `sdk-v{VERSION}` tag creation.
+
+### CLI Release
+
+The CLI is published through npm. Start releases from `apps/cli` with the `publish-cli` skill. The skill should guide the release prep, then offer the GitHub Actions publish path and the local publish path.
+
+Under the hood, every release starts the same way: prepare one release commit, then choose how to publish it.
+
+Prepare the release commit from the code you want to release:
+
+1. Draft user-facing release notes from the commits since the last `cli-vX.Y.Z` tag.
+2. Choose the release version.
+3. Update `apps/cli/package.json`.
+4. Add the approved notes to `apps/cli/CHANGELOG.md`.
+5. Run the requested checks.
+6. Commit the version and changelog changes.
+
+Then publish that release commit with one of these paths.
+
+Path A: publish from GitHub Actions.
+
+Use this for normal releases. Merge the release commit to `main`, create and push the matching release tag, then run:
+
+```sh
+git tag -a cli-vX.Y.Z -m "CLI vX.Y.Z"
+git push origin refs/tags/cli-vX.Y.Z
+gh workflow run cli-publish.yml -f publish_target=main -f git_tag=cli-vX.Y.Z -f confirm_publish=publish
+```
+
+The workflow checks out the provided `cli-vX.Y.Z` tag, verifies it matches `apps/cli/package.json`, builds the platform packages, publishes to npm with the `latest` dist-tag, creates the GitHub release, and posts to Slack.
+
+Path B: publish locally.
+
+Use this when publishing from an authenticated local machine. Start from a clean checkout at the release commit:
+
+```sh
+gh auth status
+npm whoami
+git tag -a cli-vX.Y.Z -m "CLI vX.Y.Z"
+git push origin refs/tags/cli-vX.Y.Z
+bun release cli
+gh release create cli-vX.Y.Z --verify-tag --title "CLI vX.Y.Z" --notes "Paste the approved release notes here."
+```
+
+The local helper verifies the working tree is clean, verifies `cli-vX.Y.Z` points at `HEAD` locally and on `origin`, runs tests, builds platform packages, and publishes to npm.
+
+Nightly release:
+
+```sh
+gh workflow run cli-publish.yml -f publish_target=nightly
+```
+
+Nightly also runs on a schedule. It publishes `X.Y.Z-nightly.TIMESTAMP` to npm with the `nightly` dist-tag and skips if there were no commits in the last 24 hours unless forced.
+
+### Manual SDK Publish
+
+If you need fine-grained control over individual steps:
+
+1. `bun run test`
+2. `bun version <version>` — updates all workspace package versions, regenerates models, formats, and builds.
+3. `rm bun.lock && bun install --lockfile-only` — regenerate the lockfile so `bun pm pack` resolves `workspace:*` to the new versions.
+4. `bun scripts/check-publish.ts` — pack tarballs, verify dependency alignment, test isolated install and module resolution.
+5. `npm login` — ensure you're authenticated with the npm registry.
+6. Publish in dependency order:
+   ```sh
+   cd packages/shared && bun publish && cd ../llms && bun publish && cd ../agents && bun publish && cd ../core && bun publish && cd ../../
+   ```
+7. For tagged production releases, create and push a git tag: `git tag -a sdk-v{VERSION} -m "SDK v{VERSION}" && git push origin sdk-v{VERSION}`.
+
+### Workspace Dependency Rules
+
+- Source manifests use `workspace:*` so `bun install` and local builds resolve correctly.
+- Published runtime workspace packages stay in `dependencies`. Bundled internals go in `devDependencies` so they don't leak into packed manifests.
+- `bun publish` resolves `workspace:*` to concrete versions when packing.
+
+### Verifying a Single Package
+
+Inspect the exact manifest that will be published:
+
+```sh
+cd ./packages/core
+tmpdir=$(mktemp -d)
+bun pm pack --destination "$tmpdir" >/dev/null
+tar -xOf "$tmpdir"/*.tgz package/package.json | jq '.version, .dependencies'
+```
+
+Check installed versions in a consuming project:
+
+```sh
+bun pm ls @cline/core @cline/agents @cline/llms
+```
+
+### CI
+
+The CI publish workflow (`.github/workflows/sdk-publish.yml`) follows the same order: build → version → check-publish → publish (shared → llms → agents → core). It supports `nightly` and `latest` channels and is triggered by manual dispatch or a daily cron.
+
+### Root Automation Scope
+
+Root scripts are intentionally narrower than the full workspace:
+
+- Root SDK build/test/version/publish flows target the publishable SDK packages only.
+- Internal packages can still be built/tested directly, but should not be swept into release automation by accident.
+- If you add a new internal package, keep it out of root publish/version/build sweeps unless you explicitly intend to publish it.

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

@@ -0,0 +1,273 @@
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/a05da977-2cb7-498a-88ca-20f24c9562e1" width="100%" />
+</p>
+
+<div align="center">
+<table>
+<tbody>
+<td align="center">
+<a href="https://discord.gg/cline" target="_blank"><strong>Discord</strong></a>
+</td>
+<td align="center">
+<a href="https://www.reddit.com/r/cline/" target="_blank"><strong>r/cline</strong></a>
+</td>
+<td align="center">
+<a href="https://github.com/cline/cline/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop" target="_blank"><strong>Feature Requests</strong></a>
+</td>
+</tbody>
+</table>
+</div>
+
+The Cline SDK is a TypeScript framework for building AI agents that can edit files, run shell commands, browse the web, call APIs, and use any custom tool you give them. It's the same engine that powers [Cline](https://github.com/cline/cline), packaged as a library you can embed in your own applications.
+
+```typescript
+import { Agent } from "@cline/sdk"
+
+const agent = new Agent({
+  providerId: "cline",
+  modelId: "openai/gpt-5.5",
+  systemPrompt: "You are a helpful coding assistant.",
+  tools: [],
+})
+
+const result = await agent.run("Create a REST API with Express and TypeScript")
+console.log(result.text)
+```
+
+That's it. The agent streams its response, calls tools if you give it any, and returns when the task is done.
+
+## Install
+
+```bash
+npm install @cline/sdk
+```
+
+## SDK Skill
+
+If you use a coding agent (Claude Code, Codex, Cline, etc.), install the [Cline SDK skill](https://github.com/cline/sdk-skill) to give your agent context on the SDK's APIs and best practices to help you build with the Cline SDK.
+
+```bash
+npx skills add cline/sdk-skill
+```
+
+Prompt it to scaffold agents, create custom tools, wire up plugins, configure providers, and more.
+
+## What You Can Build
+
+Coding agents, Slack bots, scheduled automations, code review pipelines, multi-agent teams, IDE integrations -- anything that benefits from an LLM that can take actions, not just generate text.
+
+```typescript
+// Slack bot: each thread gets its own agent with conversation memory
+const agents = new Map<string, Agent>()
+
+async function handleMessage(threadId: string, message: string) {
+  let agent = agents.get(threadId)
+  if (!agent) {
+    agent = new Agent({
+      providerId: "gemini",
+      modelId: "gemini-3.1-pro-preview",
+      systemPrompt: "You are a concise Slack assistant.",
+      tools: [],
+    })
+    agents.set(threadId, agent)
+  }
+
+  const result = agent.hasRun
+    ? await agent.continue(message)
+    : await agent.run(message)
+
+  return result.text
+}
+```
+
+Explore full working examples in [`examples/`](examples) and app examples in [`apps/examples/`](apps/examples):
+
+| Example | Description |
+|---------|-------------|
+| [Plugins](examples/plugins) | Custom tools with workspace-aware context, lifecycle hooks, and branch-level safety policies |
+| [Subagent Orchestration](examples/plugins/agents-squad) | Spawn and manage background agents with presets, skills, and cross-agent handoffs |
+| [Hooks](examples/hooks) | File-based and runtime hooks for logging, review gates, context injection, and lifecycle automation |
+| [Cron Automations](examples/cron) | Recurring and event-driven automation specs for scheduled quality checks and PR workflows |
+| [Desktop App](apps/examples/desktop-app) | Tauri desktop shell with a Bun sidecar backend and Next.js UI |
+| [VS Code Extension App](apps/examples/vscode) | VS Code extension example that runs Cline sessions over the RPC runtime |
+
+## Custom Tools
+
+Tools are how agents interact with the world. Define a tool with a name, a description the model reads, a JSON Schema for inputs, and a function that does the work:
+
+```typescript
+import { createTool } from "@cline/sdk"
+
+const deploy = createTool({
+  name: "deploy",
+  description: "Deploy the app to staging or production.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      environment: { type: "string", enum: ["staging", "production"] },
+    },
+    required: ["environment"],
+  },
+  execute: async (input) => {
+    const result = await runDeployment(input.environment)
+    return { url: result.url, status: "success" }
+  },
+})
+
+const agent = new Agent({
+  providerId: "moonshot",
+  modelId: "kimi-k2.5",
+  systemPrompt: "You are a deployment assistant.",
+  tools: [deploy],
+})
+```
+
+The agent decides when to call the tool based on the description. It sees the result and incorporates it into its response.
+
+## Streaming Events
+
+Every event during execution is observable in real time:
+
+```typescript
+const agent = new Agent({
+  providerId: "anthropic",
+  modelId: "claude-opus-4-7",
+  systemPrompt: "You are a helpful assistant.",
+  tools: [myTool],
+  onEvent: (event) => {
+    switch (event.type) {
+      case "content_update":
+        if (event.contentType === "text") process.stdout.write(event.text)
+        break
+      case "content_start":
+        if (event.contentType === "tool") console.log(`\n[${event.toolName}]`)
+        break
+      case "usage":
+        console.log(`\ntokens: ${event.inputTokens} in, ${event.outputTokens} out`)
+        break
+    }
+  },
+})
+```
+
+## Plugins
+
+Package reusable capabilities as extensions. An extension can register tools, observe lifecycle events, and modify agent behavior:
+
+```typescript
+const metrics: AgentPlugin = {
+  name: "metrics",
+  manifest: { capabilities: ["tools", "hooks"] },
+
+  setup(api) {
+    api.registerTool(myCustomTool)
+  },
+
+  hooks: {
+    beforeRun() {
+      console.time("agent")
+    },
+
+    beforeTool({ toolCall }) {
+      console.log(`tool: ${toolCall.toolName}`)
+    },
+
+    afterRun({ result }) {
+      console.timeEnd("agent")
+      console.log(`${result.iterations} iterations, ${result.usage.outputTokens} tokens`)
+    },
+  },
+}
+```
+
+## ClineCore: Full Runtime
+
+When you need session persistence, built-in tools, config discovery, and multi-process support, use `ClineCore`:
+
+```typescript
+import { ClineCore } from "@cline/sdk"
+
+const cline = await ClineCore.create({ clientName: "my-app" })
+
+const session = await cline.start({
+  prompt: "Set up CI with GitHub Actions",
+  config: {
+    providerId: "anthropic",
+    modelId: "claude-sonnet-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    cwd: "/path/to/project",
+    enableTools: true,
+  },
+})
+
+console.log(session.result?.text)
+```
+
+`ClineCore` gives the agent built-in tools (`bash`, `editor`, `read_files`, `apply_patch`, `search`, `fetch_web`), persists sessions to SQLite, discovers config from `.cline/` directories, and optionally connects to an RPC sidecar for scheduled agents and cross-process session management.
+
+## Packages
+
+The SDK is a layered stack. Use as much or as little as you need:
+
+| Package | What it does |
+|---------|-------------|
+| `@cline/sdk` | Everything you need -- install this one |
+| `@cline/core` | Sessions, persistence, built-in tools, config discovery, RPC |
+| `@cline/agents` | Stateless agent loop with tool execution and streaming |
+| `@cline/llms` | LLM provider gateway (Anthropic, OpenAI, Google, Bedrock, Mistral, and more) |
+| `@cline/shared` | Types, tool creation helpers, hook engine |
+
+`@cline/sdk` is an alias for `@cline/core` that re-exports from all packages, so a single install gives you the full API. The individual packages are available if you want a minimal dependency footprint.
+
+## CLI
+
+The Cline CLI gives you terminal access to the full SDK:
+
+```bash
+# Interactive agent
+cline
+
+# Single prompt
+cline "Refactor the auth module to use JWT"
+
+# Schedule an agent to run daily
+cline schedule create "PR summary" --cron "0 9 * * MON-FRI" --prompt "Summarize open PRs"
+
+# Connect a Telegram bot created with @BotFather
+cline connect telegram -k "$TELEGRAM_BOT_TOKEN"
+# Then send /help or /start to the bot in Telegram
+```
+
+For Telegram-specific connector behavior, see [`apps/cli/src/connectors/adapters/telegram.md`](./apps/cli/src/connectors/adapters/telegram.md).
+
+## Providers
+
+Works with every major LLM provider out of the box:
+
+| Provider | Models |
+|----------|--------|
+| Anthropic | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 |
+| OpenAI | GPT-5.5, GPT-5.3 Codex |
+| Google | Gemini 3.1 Pro Preview, Gemini 3 Flash Preview |
+| AWS Bedrock | Claude, Llama |
+| Mistral | Mistral Large, Codestral |
+| Any OpenAI-compatible | vLLM, Together, Fireworks, Groq, etc. |
+
+## Documentation
+
+Full documentation at [docs.cline.bot/sdk](https://docs.cline.bot/sdk/overview):
+
+- [Quickstart](https://docs.cline.bot/sdk/quickstart) -- zero to running agent in 5 minutes
+- [Core Concepts](https://docs.cline.bot/sdk/agents) -- agents, sessions, tools, events, extensions, hooks
+- [Guides](https://docs.cline.bot/sdk/guides/building-an-agent) -- end-to-end tutorials for common patterns
+- [Architecture](https://docs.cline.bot/sdk/architecture/overview) -- how the SDK is structured and why
+- [API Reference](https://docs.cline.bot/sdk/reference/cline-core) -- every method, type, and config option
+
+
+## Contributing
+
+To contribute to the project, start with our [Contributing Guide](CONTRIBUTING.md) to learn the basics. You can also join our [Discord](https://discord.gg/cline) to chat with other contributors in the `#contributors` channel. If you're looking for full-time work, check out our open positions on our [careers page](https://cline.bot/join-us)!
+
+## License
+
+[Apache 2.0 © 2026 Cline Bot Inc.](./LICENSE)

codna/agent-core/vendor/cline/sdk/biome.json

@@ -0,0 +1,140 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.5/schema.json",
+	"root": false,
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": true
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"suspicious": {
+				"noConfusingVoidType": "info",
+				"noExplicitAny": "info",
+				"noAssignInExpressions": "info",
+				"noArrayIndexKey": "info",
+				"noUnknownAtRules": {
+					"level": "info",
+					"options": {
+						"ignore": [
+							"tailwind",
+							"layer",
+							"apply",
+							"responsive",
+							"screen",
+							"variants"
+						]
+					}
+				}
+			},
+			"style": {
+				"noNonNullAssertion": "info",
+				"noRestrictedImports": {
+					"level": "error",
+					"options": {
+						"patterns": [
+							{
+								"group": [
+									"@cline/llms/*",
+									"@cline/agents/*",
+									"@cline/core/*",
+									"@cline/shared/*",
+									"**/llms/src/**",
+									"**/agents/src/**",
+									"**/core/src/**",
+									"**/shared/src/**",
+									"**/rpc/src/**",
+									"**/scheduler/src/**",
+									"!@cline/llms/node",
+									"!@cline/llms/browser",
+									"!@cline/llms/runtime",
+									"!@cline/llms/runtime/*",
+									"!@cline/llms/models",
+									"!@cline/llms/models/*",
+									"!@cline/llms/providers",
+									"!@cline/llms/providers/*",
+									"!@cline/agents/node",
+									"!@cline/agents/browser",
+									"!@cline/core/hub",
+									"!@cline/core/telemetry",
+									"!@cline/core/rpc",
+									"!@cline/shared/browser",
+									"!@cline/shared/types",
+									"!@cline/shared/storage",
+									"!@cline/shared/db"
+								],
+								"message": "Use package entrypoints for cross-package imports. Do not import from another package's internal files."
+							}
+						]
+					}
+				}
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"css": {
+		"parser": {
+			"tailwindDirectives": true
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	},
+	"json": {
+		"formatter": {
+			"enabled": true
+		}
+	},
+	"overrides": [
+		{
+			"includes": ["docs/**"],
+			"linter": {
+				"rules": {
+					"a11y": {
+						"noStaticElementInteractions": "off",
+						"useKeyWithClickEvents": "off",
+						"noSvgWithoutTitle": "off",
+						"useFocusableInteractive": "off",
+						"useSemanticElements": "off",
+						"useAriaPropsForRole": "off"
+					},
+					"security": {
+						"noDangerouslySetInnerHtml": "off"
+					},
+					"suspicious": {
+						"noDocumentCookie": "off"
+					}
+				}
+			}
+		},
+		{
+			"includes": ["../apps/cli/src/tui/**"],
+			"linter": {
+				"rules": {
+					"a11y": {
+						"noStaticElementInteractions": "off",
+						"useKeyWithClickEvents": "off"
+					}
+				}
+			}
+		}
+	]
+}