[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82792":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":15,"starSnapshotCount":15,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},82792,"harbor-sdk","zonko-ai\u002Fharbor-sdk","zonko-ai","Connect your agents with anything. Make your tools composable. Secrets stay out of agent context.","https:\u002F\u002Fwww.tryharbor.ai",null,"Python",399,10,1,0,12,61,336,41,93.12,"MIT License",false,"main",[25,26,27,28],"agent-execution","agent-tools","codemode","mit-license","2026-06-12 04:01:39","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"docs\u002Fassets\u002Fharbor-logo.png\" alt=\"Harbor\" width=\"220\" \u002F>\n\n# Harbor SDK\n\n**Publish-ready TypeScript and Python packages for building with Harbor.**\n\nPromise-first TypeScript clients, sync and async Python clients, generated\nprotocol types, runtime execution results, plugin and registry contracts,\nplatform adapters, and a local Harbor-compatible development server with a\nbuilt-in browser frontend.\n\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.9-3178c6?logo=typescript&logoColor=white)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![Bun](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBun-1.3-fbf0df?logo=bun&logoColor=black)](https:\u002F\u002Fbun.sh\u002F)\n[![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FModel_Context_Protocol-1.x-1f6feb)](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg)](.\u002FLICENSE)\n[![Status](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FStatus-Pre--release-orange)](#roadmap)\n\nPrefer the hosted control plane with workspace-scoped credentials, team sharing,\nand the full Harbor dashboard? Use **[tryharbor.ai](https:\u002F\u002Ftryharbor.ai)**.\n\n\u003C\u002Fdiv>\n\n---\n\n\u003Cdiv align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Flocal-harbor-demo.gif\" alt=\"Local Harbor demo\" width=\"860\" \u002F>\n\u003C\u002Fdiv>\n\n---\n\n## Table of Contents\n\n- [Why Harbor SDK](#why-harbor-sdk)\n- [Public Packages](#public-packages)\n- [Key Features](#key-features)\n- [Architecture at a Glance](#architecture-at-a-glance)\n- [Quickstart](#quickstart)\n- [Use the Client](#use-the-client)\n- [Use the Python Client](#use-the-python-client)\n- [Local Platform Frontend](#local-platform-frontend)\n- [Examples](#examples)\n- [Project Layout](#project-layout)\n- [Development](#development)\n- [Security Model](#security-model)\n- [Publishing](#publishing)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n---\n\n## Why Harbor SDK\n\nMost agent and tool integrations end up in one of two weak shapes:\n\n1. Hardcoded provider clients inside the app or agent, with little auditability.\n2. A hosted platform dependency before the developer has proved the workflow.\n\nHarbor SDK keeps the public package surface small while still exposing the real\nbuilding blocks:\n\n- app code can use a normal Promise client through `@hrbr\u002Fclient`,\n- system code can import stable Harbor namespaces through `@hrbr\u002Fsdk`,\n- local development can run a Harbor-compatible server and frontend without the\n  hosted dashboard,\n- runtime results preserve raw JSON and expose language-friendly content blocks\n  for text, JSON, and explicit skill bundles.\n\nThis repo is the publish-shaped package repo. Source generation still happens in\nthe Harbor monorepo; this repository stores the npm artifacts and runnable\nexamples in the shape external developers consume.\n\n---\n\n## Public Packages\n\n| Package | Purpose |\n| --- | --- |\n| `@hrbr\u002Fclient` | Promise-first Harbor API client for application, browser, integration, CLI, and server authors. Includes `@hrbr\u002Fclient\u002Feffect` for Effect-native hosts. |\n| `@hrbr\u002Fsdk` | Composite system SDK facade for Harbor runtime, platform, plugin, protocol, registry, Orbit, and control-plane contracts. |\n| `harbor-sdk` | Python client SDK published from `packages\u002Fpython`, with sync and async clients over the same generated Harbor protocol. |\n\nThe intended public npm surface is two packages. The Python surface is one PyPI\npackage named `harbor-sdk` with import package `harbor_sdk`. Leaf\nruntime\u002Fprotocol\u002Fplatform packages stay behind `@hrbr\u002Fsdk` unless there is a\nconcrete reason to expose a new public product.\n\n---\n\n## Key Features\n\n| Capability | What you get |\n| --- | --- |\n| Promise-first client | `createHarborClient()` returns ordinary Promises for app and integration code. |\n| Effect variant | `@hrbr\u002Fclient\u002Feffect` exposes the same client surface as Effect values and a layer. |\n| Python client | `HarborClient` and `AsyncHarborClient` expose sync\u002Fasync Python calls with typed runtime content blocks. |\n| Generated protocol client | `harbor.api` and `@hrbr\u002Fclient\u002Fgenerated\u002Fharbor` expose generated Harbor API resources and types. |\n| Explicit auth modes | Workspace API keys, bearer tokens, token providers, OAuth authorize URL helpers, and device-login helpers. |\n| Runtime results | `runtime.execute` preserves raw `result` and typed `content` blocks, including explicit skill bundles. |\n| System namespaces | `@hrbr\u002Fsdk` exports `Agents`, `Core`, `Orbit`, `Platform`, `Plugins`, `Protocol`, `Registry`, and `Runtime`. |\n| Focused subpaths | Narrow imports such as `@hrbr\u002Fsdk\u002Fcore\u002Ftrigger`, `@hrbr\u002Fsdk\u002Fregistry`, and `@hrbr\u002Fsdk\u002Fplatform\u002Flocal`. |\n| Local server | `@hrbr\u002Fsdk\u002Fplatform\u002Flocal` can initialize a local project, serve Harbor-compatible routes, record runs, and host a small frontend. |\n| Packaged artifacts | Package directories contain `dist`, declaration files, modern `exports`, and npm publish metadata. |\n\n---\n\n## Architecture at a Glance\n\n```text\n┌────────────────────────────────────────────────────────────────────┐\n│                    Application \u002F agent \u002F integration                │\n│       browser app, server job, CLI, desktop app, or test harness     │\n└─────────────────────┬───────────────────────────┬──────────────────┘\n                      │                           │\n                      ▼                           ▼\n          ┌──────────────────────┐     ┌──────────────────────────┐\n          │     @hrbr\u002Fclient     │     │        @hrbr\u002Fsdk          │\n          │ Promise API client   │     │ Composite system facade   │\n          │ Effect subpath       │     │ Core\u002FRuntime\u002FPlatform\u002F... │\n          └──────────┬───────────┘     └───────────┬──────────────┘\n                     │                             │\n                     ▼                             ▼\n       Hosted Harbor API                 Local platform \u002F contracts\n       https:\u002F\u002Fapi.tryharbor.ai          @hrbr\u002Fsdk\u002Fplatform\u002Flocal\n                     │                             │\n                     ▼                             ▼\n           workspaces, runs,         local project store, run records,\n           plugins, sources,         local frontend, runtime host hook\n           triggers, workflows\n```\n\n---\n\n## Quickstart\n\n> Prerequisites: [Bun](https:\u002F\u002Fbun.sh\u002F) 1.3+ and Node 22+.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fzonko-ai\u002Fharbor-sdk.git\ncd harbor-sdk\nbun install\nbun run typecheck\nbun run smoke\nbun run python:sdk:test\n```\n\nRun the local frontend example:\n\n```bash\nbun run --filter local-platform-example serve\n```\n\nOpen the printed `http:\u002F\u002F127.0.0.1:\u003Cport>` URL. The example uses\n`local-token` as its bearer token when the frontend asks for auth.\n\n---\n\n## Use the Client\n\n```ts\nimport { createHarborClient } from '@hrbr\u002Fclient'\n\nconst harbor = createHarborClient({\n  baseUrl: 'https:\u002F\u002Fapi.tryharbor.ai',\n  workspaceId: process.env.HARBOR_WORKSPACE_ID!,\n  auth: { kind: 'api_key', key: process.env.HARBOR_API_KEY! },\n})\n\nconst exec = await harbor.runtime.execute({\n  code: 'return \"hello from Harbor\"',\n})\n\nconsole.log(exec.result)\nconsole.log(exec.content?.[0])\n```\n\nFor browser and app-owned OAuth flows, keep token storage in the application and\npass a provider into the client:\n\n```ts\nconst harbor = createHarborClient({\n  baseUrl: 'https:\u002F\u002Fapi.tryharbor.ai',\n  auth: {\n    kind: 'bearer',\n    tokenProvider: async () => await getCurrentAccessToken(),\n  },\n})\n\nconst workspaces = await harbor.workspaces.list({ limit: 25 })\n```\n\nUse `@hrbr\u002Fclient\u002Feffect` when the host application wants Effect-native calls\ninstead of Promises.\n\n---\n\n## Use the Python Client\n\n```python\nfrom harbor_sdk import HarborClient\n\nclient = HarborClient(\n    api_key=\"hrbr_...\",\n    workspace_id=\"workspace_...\",\n)\n\nrun = client.runtime.execute(code='return \"hello from Harbor\"')\n\nprint(run.result)\nfor block in run.content or []:\n    if block.type == \"text\":\n        print(block.text)\n    elif block.type == \"json\":\n        print(block.json_)\n    elif block.type == \"skill_bundle\":\n        print(block.skill.slug)\n```\n\nAsync hosts use the same shape:\n\n```python\nfrom harbor_sdk import AsyncHarborClient\n\nclient = AsyncHarborClient(\n    api_key=\"hrbr_...\",\n    workspace_id=\"workspace_...\",\n)\n\nrun = await client.runtime.execute(code='return \"hello from Harbor\"')\n```\n\n`api_key` defaults to `HARBOR_API_KEY`, `workspace_id` defaults to\n`HARBOR_WORKSPACE_ID`, and `base_url` defaults to `https:\u002F\u002Fapi.tryharbor.ai`.\nThe generated protocol layer is exposed as `harbor_sdk_generated`; application\ncode should prefer the public `harbor_sdk` facade.\n\n---\n\n## Local Platform Frontend\n\n`@hrbr\u002Fsdk\u002Fplatform\u002Flocal` is the SDK-local infrastructure surface. It is not\nthe full hosted Harbor dashboard, but it is enough to exercise a local\nHarbor-compatible server and frontend.\n\n```ts\nimport { createHarborClient } from '@hrbr\u002Fclient'\nimport { Effect } from 'effect'\nimport { initLocalProject, startLocalHarborServer } from '@hrbr\u002Fsdk\u002Fplatform\u002Flocal'\n\nconst project = initLocalProject({\n  workspaceId: 'workspace_local',\n  workspaceName: 'Local SDK Workspace',\n  authToken: 'local-token',\n})\n\nconst server = await startLocalHarborServer({\n  project,\n  authToken: 'local-token',\n  runtimeHost: (invocation) =>\n    Effect.succeed({\n      mode: invocation.request.mode,\n      result: { ok: true, scopeId: invocation.context.scopeId },\n      logs: [],\n      warnings: [],\n      timings: {},\n    }),\n})\n\nconst harbor = createHarborClient({\n  baseUrl: server.url,\n  workspaceId: 'workspace_local',\n  auth: { kind: 'bearer', token: 'local-token' },\n})\n\nawait harbor.runtime.execute({ code: 'return { ok: true }' })\n```\n\nThe server exposes the SDK-local frontend at `\u002F`, the frontend script at\n`\u002Flocal\u002Ffrontend.js`, health at `\u002Fhealthz`, and Harbor-compatible JSON\nroutes for the local workspace\u002Frun flow used by the examples.\n\n---\n\n## Examples\n\n| Example | What it shows |\n| --- | --- |\n| `examples\u002Fbrowser-client` | Browser\u002Fapp integration with caller-owned bearer token state. |\n| `examples\u002Fclient-promise` | Promise runtime execution and content blocks for text plus explicit skill bundles. |\n| `examples\u002Fpython-client` | Offline Python client call showing text, JSON, and skill-bundle content blocks. |\n| `examples\u002Fsdk-system` | Root namespace imports and focused subpaths from `@hrbr\u002Fsdk`. |\n| `examples\u002Flocal-platform` | Local project, local server, SDK client call, and built-in frontend. |\n\nRun all examples through the smoke command:\n\n```bash\nbun run smoke\n```\n\n---\n\n## Project Layout\n\n```text\nharbor-sdk\u002F\n├── docs\u002Fassets\u002F              # logo and demo media used by this README\n├── examples\u002F\n│   ├── browser-client\u002F\n│   ├── client-promise\u002F\n│   ├── python-client\u002F\n│   ├── local-platform\u002F\n│   └── sdk-system\u002F\n├── packages\u002F\n│   ├── client\u002F               # generated @hrbr\u002Fclient package\n│   ├── python\u002F               # Python harbor-sdk package\n│   └── sdk\u002F                  # generated @hrbr\u002Fsdk package\n├── LICENSE\n├── package.json\n└── README.md\n```\n\n---\n\n## Development\n\n```bash\nbun install\nbun run typecheck\nbun run smoke\nbun run pack:dry-run\nbun run python:sdk:test\n```\n\nThe package directories are generated artifacts. For broad source changes,\nrefresh them from the Harbor monorepo publish pipeline, then re-run the checks\nabove in this repository.\n\n---\n\n## Security Model\n\n- `@hrbr\u002Fclient` does not own browser cookies, OAuth refresh storage, or app\n  sessions. The host application owns credentials and passes a token or provider.\n- Workspace API-key clients require an explicit `workspaceId` before runtime\n  and workspace-scoped helper calls.\n- Skill bundles are never inferred from arbitrary returned objects. User code\n  must return the explicit Harbor execute-result envelope for SDKs to expose a\n  loadable skill bundle.\n- The local platform server is for single-user development and test harnesses.\n  Keep it on loopback and configure `authToken` when exposing the frontend.\n- The hosted Harbor dashboard, WorkOS\u002FAuthKit configuration, shared credential\n  vault, and team governance live in the Harbor product, not in this package\n  repository.\n\n---\n\n## Publishing\n\nPublish from the package directories after generated artifacts have been\nrefreshed and verified:\n\n```bash\nnpm publish .\u002Fpackages\u002Fclient --access public\nnpm publish .\u002Fpackages\u002Fsdk --access public\nbun run python:sdk:pack\npython3 -m twine upload tmp\u002Fpython-dist\u002Fharbor_sdk-*.whl\n```\n\nUse the source Harbor monorepo publish smoke before refreshing this repository\nso stale intermediate tarballs do not get copied here.\n\n---\n\n## Roadmap\n\n- [ ] Publish `@hrbr\u002Fclient` and `@hrbr\u002Fsdk` to npm.\n- [ ] Publish `harbor-sdk` to PyPI.\n- [ ] Add more framework examples for browser, server, CLI, and worker hosts.\n- [ ] Keep local platform frontend examples aligned with the hosted Harbor API\n      contract.\n- [ ] Add release automation that proves pack\u002Finstall smokes before publish.\n\n---\n\n## License\n\nReleased under the [MIT License](.\u002FLICENSE).\n\n\u003Cdiv align=\"center\">\n\nBuilt by Zonko Team\n\n\u003C\u002Fdiv>\n","Harbor SDK 是一个用于构建与 Harbor 兼容的应用程序的工具包，支持 TypeScript 和 Python。其核心功能包括 Promise-first 的 TypeScript 客户端、同步和异步的 Python 客户端、生成的协议类型以及本地开发服务器等。技术特点上，它采用了 TypeScript 5.9 和 Bun 1.3，并遵循 Model Context Protocol 1.x 标准。此外，Harbor SDK 还特别强调了安全性和可组合性，确保敏感信息不会暴露在代理环境中。适用于需要将各种工具或服务集成到单一平台中以实现更高效协作的场景，如开发团队内部工具链整合、自动化工作流创建等。",2,"2026-06-11 04:09:16","CREATED_QUERY"]