orbit-code-ai 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+NOTICE
+
+This repository contains code derived from Anthropic's Orbit CLI.
+
+The original Orbit source is proprietary software:
+  Copyright (c) Anthropic PBC. All rights reserved.
+  Subject to Anthropic's Commercial Terms of Service.
+
+Modifications and additions by Orbit contributors are offered under
+the MIT License where legally permissible:
+
+  MIT License
+  Copyright (c) 2026 Orbit contributors (modifications only)
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of the modifications made by Orbit contributors, to deal
+  in those modifications without restriction, including without limitation
+  the rights to use, copy, modify, merge, publish, distribute, sublicense,
+  and/or sell copies, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the modifications.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+
+The underlying derived code remains subject to Anthropic's copyright.
+This project does not have Anthropic's authorization to distribute
+their proprietary source. Users and contributors should evaluate their
+own legal position.

package/README.md

@@ -0,0 +1,326 @@
+# Orbit
+
+Orbit is an open-source coding-agent CLI for cloud and local model providers.
+
+Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, and other supported backends while keeping one terminal-first workflow: prompts, tools, agents, MCP, slash commands, and streaming output.
+
+[![PR Checks](https://github.com/Gitlawb/orbit/actions/workflows/pr-checks.yml/badge.svg?branch=main)](https://github.com/Gitlawb/orbit/actions/workflows/pr-checks.yml)
+[![Release](https://img.shields.io/github/v/tag/Gitlawb/orbit?label=release&color=0ea5e9)](https://github.com/Gitlawb/orbit/tags)
+[![Discussions](https://img.shields.io/badge/discussions-open-7c3aed)](https://github.com/Gitlawb/orbit/discussions)
+[![Security Policy](https://img.shields.io/badge/security-policy-0f766e)](SECURITY.md)
+[![License](https://img.shields.io/badge/license-MIT-2563eb)](LICENSE)
+
+[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community)
+
+## Why Orbit
+
+- Use one CLI across cloud APIs and local model backends
+- Save provider profiles inside the app with `/provider`
+- Run with OpenAI-compatible services, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, and other supported providers
+- Keep coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
+- Use the bundled VS Code extension for launch integration and theme support
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @gitlawb/orbit
+```
+
+If the install later reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting Orbit.
+
+### Start
+
+```bash
+orbit
+```
+
+Inside Orbit:
+
+- run `/provider` for guided provider setup and saved profiles
+- run `/onboard-github` for GitHub Models onboarding
+
+### Fastest OpenAI setup
+
+macOS / Linux:
+
+```bash
+export ORBIT_CODE_USE_OPENAI=1
+export OPENAI_API_KEY=sk-your-key-here
+export OPENAI_MODEL=gpt-4o
+
+orbit
+```
+
+Windows PowerShell:
+
+```powershell
+$env:ORBIT_CODE_USE_OPENAI="1"
+$env:OPENAI_API_KEY="sk-your-key-here"
+$env:OPENAI_MODEL="gpt-4o"
+
+orbit
+```
+
+### Fastest local Ollama setup
+
+macOS / Linux:
+
+```bash
+export ORBIT_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=http://localhost:11434/v1
+export OPENAI_MODEL=qwen2.5-coder:7b
+
+orbit
+```
+
+Windows PowerShell:
+
+```powershell
+$env:ORBIT_CODE_USE_OPENAI="1"
+$env:OPENAI_BASE_URL="http://localhost:11434/v1"
+$env:OPENAI_MODEL="qwen2.5-coder:7b"
+
+orbit
+```
+
+## Setup Guides
+
+Beginner-friendly guides:
+
+- [Non-Technical Setup](docs/non-technical-setup.md)
+- [Windows Quick Start](docs/quick-start-windows.md)
+- [macOS / Linux Quick Start](docs/quick-start-mac-linux.md)
+
+Advanced and source-build guides:
+
+- [Advanced Setup](docs/advanced-setup.md)
+- [Android Install](ANDROID_INSTALL.md)
+
+## Supported Providers
+
+| Provider | Setup Path | Notes |
+| --- | --- | --- |
+| OpenAI-compatible | `/provider` or env vars | Works with OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio, and other compatible `/v1` servers |
+| Gemini | `/provider` or env vars | Supports API key, access token, or local ADC workflow on current `main` |
+| GitHub Models | `/onboard-github` | Interactive onboarding with saved credentials |
+| Codex | `/provider` | Uses existing Codex credentials when available |
+| Ollama | `/provider` or env vars | Local inference with no API key |
+| Atomic Chat | advanced setup | Local Apple Silicon backend |
+| Bedrock / Vertex / Foundry | env vars | Additional provider integrations for supported environments |
+
+## What Works
+
+- **Tool-driven coding workflows**: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
+- **Streaming responses**: Real-time token output and tool progress
+- **Tool calling**: Multi-step tool loops with model calls, tool execution, and follow-up responses
+- **Images**: URL and base64 image inputs for providers that support vision
+- **Provider profiles**: Guided setup plus saved `.orbit-profile.json` support
+- **Local and remote model backends**: Cloud APIs, local servers, and Apple Silicon local inference
+
+## Provider Notes
+
+Orbit supports multiple providers, but behavior is not identical across all of them.
+
+- Anthropic-specific features may not exist on other providers
+- Tool quality depends heavily on the selected model
+- Smaller local models can struggle with long multi-step tool flows
+- Some providers impose lower output caps than the CLI defaults, and Orbit adapts where possible
+
+For best results, use models with strong tool/function calling support.
+
+## Agent Routing
+
+Orbit can route different agents to different models through settings-based routing. This is useful for cost optimization or splitting work by model strength.
+
+Add to `~/.orbit/settings.json`:
+
+```json
+{
+  "agentModels": {
+    "deepseek-chat": {
+      "base_url": "https://api.deepseek.com/v1",
+      "api_key": "sk-your-key"
+    },
+    "gpt-4o": {
+      "base_url": "https://api.openai.com/v1",
+      "api_key": "sk-your-key"
+    }
+  },
+  "agentRouting": {
+    "Explore": "deepseek-chat",
+    "Plan": "gpt-4o",
+    "general-purpose": "gpt-4o",
+    "frontend-dev": "deepseek-chat",
+    "default": "gpt-4o"
+  }
+}
+```
+
+When no routing match is found, the global provider remains the fallback.
+
+> **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep this file private and do not commit it to version control.
+
+## Web Search and Fetch
+
+By default, `WebSearch` works on non-Anthropic models using DuckDuckGo. This gives GPT-4o, DeepSeek, Gemini, Ollama, and other OpenAI-compatible providers a free web search path out of the box.
+
+> **Note:** DuckDuckGo fallback works by scraping search results and may be rate-limited, blocked, or subject to DuckDuckGo's Terms of Service. If you want a more reliable supported option, configure Firecrawl.
+
+For Anthropic-native backends and Codex responses, Orbit keeps the native provider web search behavior.
+
+`WebFetch` works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.
+
+Set a [Firecrawl](https://firecrawl.dev) API key if you want Firecrawl-powered search/fetch behavior:
+
+```bash
+export FIRECRAWL_API_KEY=your-key-here
+```
+
+With Firecrawl enabled:
+
+- `WebSearch` can use Firecrawl's search API while DuckDuckGo remains the default free path for non-Orbit models
+- `WebFetch` uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly
+
+Free tier at [firecrawl.dev](https://firecrawl.dev) includes 500 credits. The key is optional.
+
+---
+
+## Headless gRPC Server
+
+Orbit can be run as a headless gRPC service, allowing you to integrate its agentic capabilities (tools, bash, file editing) into other applications, CI/CD pipelines, or custom user interfaces. The server uses bidirectional streaming to send real-time text chunks, tool calls, and request permissions for sensitive commands.
+
+### 1. Start the gRPC Server
+
+Start the core engine as a gRPC service on `localhost:50051`:
+
+```bash
+npm run dev:grpc
+```
+
+#### Configuration
+
+| Variable | Default | Description |
+|-----------|-------------|------------------------------------------------|
+| `GRPC_PORT` | `50051` | Port the gRPC server listens on |
+| `GRPC_HOST` | `localhost` | Bind address. Use `0.0.0.0` to expose on all interfaces (not recommended without authentication) |
+
+### 2. Run the Test CLI Client
+
+We provide a lightweight CLI client that communicates exclusively over gRPC. It acts just like the main interactive CLI, rendering colors, streaming tokens, and prompting you for tool permissions (y/n) via the gRPC `action_required` event.
+
+In a separate terminal, run:
+
+```bash
+npm run dev:grpc:cli
+```
+
+*Note: The gRPC definitions are located in `src/proto/orbit.proto`. You can use this file to generate clients in Python, Go, Rust, or any other language.*
+
+---
+
+## Source Build And Local Development
+
+```bash
+bun install
+bun run build
+node dist/cli.mjs
+```
+
+Helpful commands:
+
+- `bun run dev`
+- `bun test`
+- `bun run test:coverage`
+- `bun run security:pr-scan -- --base origin/main`
+- `bun run smoke`
+- `bun run doctor:runtime`
+- `bun run verify:privacy`
+- focused `bun test ...` runs for the areas you touch
+
+## Testing And Coverage
+
+Orbit uses Bun's built-in test runner for unit tests.
+
+Run the full unit suite:
+
+```bash
+bun test
+```
+
+Generate unit test coverage:
+
+```bash
+bun run test:coverage
+```
+
+Open the visual coverage report:
+
+```bash
+open coverage/index.html
+```
+
+If you already have `coverage/lcov.info` and only want to rebuild the UI:
+
+```bash
+bun run test:coverage:ui
+```
+
+Use focused test runs when you only touch one area:
+
+- `bun run test:provider`
+- `bun run test:provider-recommendation`
+- `bun test path/to/file.test.ts`
+
+Recommended contributor validation before opening a PR:
+
+- `bun run build`
+- `bun run smoke`
+- `bun run test:coverage` for broader unit coverage when your change affects shared runtime or provider logic
+- focused `bun test ...` runs for the files and flows you changed
+
+Coverage output is written to `coverage/lcov.info`, and Orbit also generates a git-activity-style heatmap at `coverage/index.html`.
+## Repository Structure
+
+- `src/` - core CLI/runtime
+- `scripts/` - build, verification, and maintenance scripts
+- `docs/` - setup, contributor, and project documentation
+- `python/` - standalone Python helpers and their tests
+- `vscode-extension/orbit-vscode/` - VS Code extension
+- `.github/` - repo automation, templates, and CI configuration
+- `bin/` - CLI launcher entrypoints
+
+## VS Code Extension
+
+The repo includes a VS Code extension in [`vscode-extension/orbit-vscode`](vscode-extension/orbit-vscode) for Orbit launch integration, provider-aware control-center UI, and theme support.
+
+## Security
+
+If you believe you found a security issue, see [SECURITY.md](SECURITY.md).
+
+## Community
+
+- Use [GitHub Discussions](https://github.com/Gitlawb/orbit/discussions) for Q&A, ideas, and community conversation
+- Use [GitHub Issues](https://github.com/Gitlawb/orbit/issues) for confirmed bugs and actionable feature work
+
+## Contributing
+
+Contributions are welcome.
+
+For larger changes, open an issue first so the scope is clear before implementation. Helpful validation commands include:
+
+- `bun run build`
+- `bun run test:coverage`
+- `bun run smoke`
+- focused `bun test ...` runs for touched areas
+
+## Disclaimer
+
+Orbit is an independent community project and is not affiliated with, endorsed by, or sponsored by Anthropic.
+
+Orbit originated from the Orbit Code codebase and has since been substantially modified to support multiple providers and open use. "Orbit" and "Orbit Code" are trademarks of Anthropic PBC. See [LICENSE](LICENSE) for details.
+
+## License
+
+See [LICENSE](LICENSE).

package/_agent_reference/components/audit-logging.md

@@ -0,0 +1,129 @@
+# Audit & Logging
+
+The framework provides configuration-driven audit logging with field masking. Every flow should audit both the incoming request and outgoing response.
+
+---
+
+## Components
+
+| Component | Type | Purpose |
+|---|---|---|
+| `AuditPoint.esql` | esql | Prepare audit message (11KB) |
+| `AuditPoint_PrepareOutgoingAuditRequest.esql` | esql | Prepare outgoing-specific audit data |
+| `LogAudit.subflow` | subflow | Log incoming request |
+| `LogOutgoingAudit.subflow` | subflow | Log outgoing response |
+| `LogError.subflow` | subflow | Log error event |
+
+---
+
+## AuditPoint.esql
+
+**Purpose**: Reads config from `Environment.Properties`, builds the audit XML structure, and routes to the audit queue.
+
+**Key behavior**:
+- Reads `AuditEnabled` and `LogEnabled` flags — does nothing if both are FALSE
+- Extracts field values using XPath expressions defined in `value1`–`value10` properties
+- Masks fields listed in `maskingIn` / `maskingOut` using EVAL (dynamic path resolution)
+- Adds flow metadata: broker name, execution group, flow name, timestamps
+
+**Masking**: Fields listed in `maskingIn`/`maskingOut` have their values replaced with `****` before logging. Example masked field: `*.Header.ChannelUserInfo.UserPassword`
+
+---
+
+## Standard Audit Structure
+
+```xml
+<Audit>
+  <auditHeader>
+    <audit>TRUE</audit>
+    <log>TRUE</log>
+    <retryCount>0</retryCount>
+    <requestId>unique-id</requestId>
+    <timestamp>2024-01-01T00:00:00.000Z</timestamp>
+    <flowStart>TRUE</flowStart>        <!-- TRUE for incoming, FALSE for outgoing -->
+    <channelId>CHANNEL</channelId>
+    <userName>user</userName>
+    <serviceCode>SVC001</serviceCode>
+    <sessionId>session</sessionId>
+    <applicationName>AppName</applicationName>
+    <messageFlowName>FlowName</messageFlowName>
+    <brokerName>BrokerName</brokerName>
+    <executionGroupName>ExecGroup</executionGroupName>
+    <logType>Information</logType>     <!-- Information | Error -->
+    <key1>CUSTOMER.NO</key1>           <!-- label from config -->
+    <value1>12345678</value1>          <!-- extracted from message -->
+    <!-- key2-key10, value2-value10 -->
+    <message><!-- full message body if LogEnabled=TRUE --></message>
+  </auditHeader>
+</Audit>
+```
+
+---
+
+## Configuration (Properties XML)
+
+Under the `Logging` group for each flow:
+
+```xml
+<group name="Logging">
+  <property name="LogEnabled"     value="TRUE" />
+  <property name="AuditEnabled"   value="TRUE" />
+  <property name="MaskingEnabled" value="TRUE" />
+
+  <!-- Audit key-value pairs: up to 10 fields to extract from message -->
+  <property name="key1"   value="CUSTOMER.NO" />
+  <property name="value1" value="*.Body.CustomerId" />
+  <property name="key2"   value="ACCOUNT.NO" />
+  <property name="value2" value="*.Body.AccountNumber" />
+
+  <!-- Fields to mask in incoming/outgoing audit -->
+  <property name="maskingIn">
+    <value>*.Header.ChannelUserInfo.UserPassword</value>
+  </property>
+  <property name="maskingOut">
+    <value>*.Header.ChannelUserInfo.UserPassword</value>
+  </property>
+</group>
+```
+
+**Notes**:
+- `key1`–`key10`: human-readable label for audit records
+- `value1`–`value10`: XPath-style path into the message tree to extract the value
+- `maskingIn`: mask these paths in the incoming request audit
+- `maskingOut`: mask these paths in the outgoing response audit
+- Always mask `*.Header.ChannelUserInfo.UserPassword` at minimum
+
+---
+
+## Wiring in a Flow
+
+```
+[Input Adapter]
+    ↓
+PropertyReader          ← must run first to load config
+    ↓
+LogAudit                ← log incoming request (flowStart=TRUE)
+    ↓
+[... flow logic ...]
+    ↓
+LogOutgoingAudit        ← log outgoing response (flowStart=FALSE)
+    ↓
+[Output Adapter]
+
+Error path:
+[Any failure] → ErrorHandler → LogError → [dead letter]
+```
+
+---
+
+## ESQL Access Pattern for Audit Flags
+
+```esql
+-- Check if audit is enabled before doing audit work
+DECLARE auditEnabled BOOLEAN;
+SET auditEnabled = Environment.Properties.{ApplicationLabel}.{flowName}.Logging.AuditEnabled;
+
+IF auditEnabled = TRUE THEN
+    -- proceed with audit
+END IF;
+```

package/_agent_reference/components/common-utils.md

@@ -0,0 +1,146 @@
+# Common Utilities (CommonUtils.esql)
+
+`CommonUtils.esql` is a 47KB shared ESQL library containing constants, queue routing, correlation ID generation, database access, and utility functions. Include it in every flow that needs routing or utility functions.
+
+**Location**: `Qiwa/Framework/Lib/CommonUtils.esql`
+
+---
+
+## Error Code Constants
+
+```esql
+-- Always use these constants, never hardcode error codes
+DECLARE ESB_SUCCESS_RESPONSE_CODE               CONSTANT CHAR '00000000';
+DECLARE ESB_RUNTIME_TECHNICAL_ERROR_CODE        CONSTANT CHAR '99999999';
+DECLARE ESB_MIDDLEWARE_DATABASE_ERROR_RESPONSE_CODE CONSTANT CHAR 'E0199998';
+```
+
+Backend-specific error code ranges are also defined — read `ErrorHandler.esql` for the full list per backend system.
+
+---
+
+## Key Functions
+
+### Queue Routing
+
+```esql
+-- Set request and response queues based on ServiceCode from message header
+-- Reads from MCR_CHANNESBFUNC_TBL database table
+CALL SetQueues(IN serviceCode CHARACTER, OUT requestQueue CHARACTER, OUT responseQueue CHARACTER);
+
+-- Get output queue for a specific channel
+CALL getChannelOutQueue(IN channelId CHARACTER, IN serviceCode CHARACTER, OUT outQueue CHARACTER);
+```
+
+### Correlation ID
+
+```esql
+-- Generate a unique correlation ID for tracking this message across systems
+CALL getChannelCorrelationID(IN channelId CHARACTER, IN sessionId CHARACTER, OUT correlationId CHARACTER);
+
+-- Get correlation ID from the ESB channel
+CALL getEsbChannelId(IN channelId CHARACTER, OUT esbChannelId CHARACTER);
+```
+
+### Timestamp
+
+```esql
+-- Get formatted timestamp string (ISO 8601)
+CALL GetTimestampFormat(OUT timestamp CHARACTER);
+-- Returns: '2024-01-15T14:30:00.000Z'
+```
+
+### Database Access
+
+```esql
+-- Execute a SQL query with error handling
+-- DSN is configured at the integration node level
+CALL MCRDB_Selection(IN sqlQuery CHARACTER, OUT resultSet ROW);
+```
+
+### Flow Name Utility
+
+```esql
+-- Strip schema prefix from flow name for use in property lookups
+CALL getFlowNameWithouSchema(IN fullFlowName CHARACTER, OUT flowName CHARACTER);
+-- Input:  'Qiwa.BS_Account.GetAccountDetails'
+-- Output: 'GetAccountDetails'
+```
+
+### Response Codes
+
+```esql
+-- Get the standard success code
+CALL GetESBSuccessCode(OUT successCode CHARACTER);
+-- Returns: '00000000'
+
+-- Get default character set
+CALL GetDefaultCharacterSet(OUT charset CHARACTER);
+-- Returns: 'UTF-8'
+```
+
+---
+
+## Shared Row (In-Memory Cache)
+
+```esql
+SHARED ROW CacheQueueTable;
+```
+
+`CacheQueueTable` is used by `SetQueues()` to cache queue routing lookups. It persists across message invocations within the same execution group — do not clear it manually.
+
+---
+
+## Database Tables Referenced
+
+| Table | Columns | Purpose |
+|---|---|---|
+| `MCR_CHANNESBFUNC_TBL` | `ESBFUNCID`, `ESBFUNCNAME`, `REQUEST_QUEUE_NAME`, `RESPONSE_QUEUE_NAME` | Queue routing by service code |
+| `MCR_CHANNAUTH_TBL` | `CHANNID`, `ESBFUNCID` | Channel authorization check |
+
+---
+
+## Usage Pattern in ESQL
+
+```esql
+-- At top of your ESQL module, no explicit import needed —
+-- CommonUtils is part of the shared library automatically
+
+-- Example: get queues for this service
+DECLARE reqQueue CHARACTER;
+DECLARE resQueue CHARACTER;
+DECLARE serviceCode CHARACTER;
+SET serviceCode = InputRoot.XMLNSC.Root.Header.ServiceCode;
+CALL SetQueues(serviceCode, reqQueue, resQueue);
+
+-- Set output destination
+SET Environment.Destination.MQ.DestinationData.queueName = reqQueue;
+
+-- Example: generate correlation ID
+DECLARE corrId CHARACTER;
+CALL getChannelCorrelationID(
+    InputRoot.XMLNSC.Root.Header.ChannelId,
+    InputRoot.XMLNSC.Root.Header.SessionId,
+    corrId
+);
+SET OutputRoot.MQMD.CorrelId = CAST(corrId AS BLOB CCSID 1208);
+```
+
+---
+
+## Standard Header Field Paths
+
+```esql
+-- Standard paths for common header fields
+InputRoot.XMLNSC.Root.Header.TransactionId
+InputRoot.XMLNSC.Root.Header.ChannelId
+InputRoot.XMLNSC.Root.Header.ServiceCode
+InputRoot.XMLNSC.Root.Header.SessionId
+InputRoot.XMLNSC.Root.Header.RequestTime
+InputRoot.XMLNSC.Root.Header.ChannelUserInfo.UserName
+InputRoot.XMLNSC.Root.Header.ChannelUserInfo.UserPassword  -- ALWAYS MASK
+InputRoot.XMLNSC.Root.Header.ResponseStatus.Code
+InputRoot.XMLNSC.Root.Header.ResponseStatus.Status
+InputRoot.XMLNSC.Root.Header.ResponseStatus.EnglishMsg
+InputRoot.XMLNSC.Root.Body                                 -- service-specific data
+```