{"_id":"@austinjan/ts-agent","name":"@austinjan/ts-agent","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@austinjan/ts-agent","version":"0.1.0-alpha.0","type":"module","description":"TypeScript-first AI agent library with provider adapters, tools, skills, audit, and permission interfaces.","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"ts-agent":"dist/cli.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","cli":"tsx src/cli.ts","typecheck":"tsc --noEmit","samples:backend":"tsx samples/backend/server.ts","samples:frontend":"vite --config samples/frontend/vite.config.ts","samples:frontend:build":"vite build --config samples/frontend/vite.config.ts","samples:frontend:typecheck":"tsc -p samples/frontend/tsconfig.json --noEmit","test":"vitest run","test:smoke":"vitest run tests/smoke.test.ts","test:e2e":"vitest run tests/e2e.test.ts","test:cache:live":"vitest run tests/openai-cache-live.test.ts","test:gemini-cache:live":"vitest run tests/gemini-cache-live.test.ts","test:gemini:live":"vitest run tests/gemini-live.test.ts","dev":"tsx src/index.ts"},"keywords":["agent","ai","typescript","openai","gemini","claude"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/austinjan/ts-agent.git"},"bugs":{"url":"https://github.com/austinjan/ts-agent/issues"},"homepage":"https://github.com/austinjan/ts-agent#readme","devDependencies":{"@types/node":"^20.12.12","@types/react":"^18.3.29","@types/react-dom":"^18.3.7","@vitejs/plugin-react":"^4.7.0","lucide-react":"^1.16.0","react":"^18.3.1","react-dom":"^18.3.1","tsx":"^4.19.2","typescript":"^5.8.3","vite":"^5.4.21","vitest":"^2.1.8"},"dependencies":{"@google/genai":"^2.4.0","openai":"^6.38.0","yaml":"^2.9.0","zod":"^3.24.1","zod-to-json-schema":"^3.25.2"},"gitHead":"20cdef8dc7bee340fef6546def428861df507555","_id":"@austinjan/ts-agent@0.1.0-alpha.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-f1AXDv9oiPaIt0P/Ip2jRlzEpKG56Wbxq5dtt1Zp8d0JrivFSi/wDhmwpvEdAHyFNIsYoWNyBBGGgjhQ7Bk4rw==","shasum":"49c794be70d04cb15061af8689d931dbb4ba0d19","tarball":"https://registry.npmjs.org/@austinjan/ts-agent/-/ts-agent-0.1.0-alpha.0.tgz","fileCount":82,"unpackedSize":225830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFuyGgEb4QlHlQzYahE/TCgGaIsovdj9O2rNuTe8q5W2AiEAw0zazbQJjKDInX4LFzXf23PfqvgZmWXsHPqwpMC8n7g="}]},"_npmUser":{"name":"austinjan","email":"austin.jan@gmail.com"},"directories":{},"maintainers":[{"name":"austinjan","email":"austin.jan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ts-agent_0.1.0-alpha.0_1780382959590_0.6752640480809973"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T06:49:19.443Z","0.1.0-alpha.0":"2026-06-02T06:49:19.755Z","modified":"2026-06-02T06:49:19.945Z"},"maintainers":[{"name":"austinjan","email":"austin.jan@gmail.com"}],"description":"TypeScript-first AI agent library with provider adapters, tools, skills, audit, and permission interfaces.","homepage":"https://github.com/austinjan/ts-agent#readme","keywords":["agent","ai","typescript","openai","gemini","claude"],"repository":{"type":"git","url":"git+https://github.com/austinjan/ts-agent.git"},"bugs":{"url":"https://github.com/austinjan/ts-agent/issues"},"license":"MIT","readme":"# ts-agent\n\nTypeScript-first AI agent library for building provider-agnostic agents.\n\nThe project now has an alpha library runtime slice. The implemented runtime supports:\n\n- Gemini and OpenAI provider adapters\n- tool use\n- skills as reusable capability bundles\n- audit trail interfaces for external integration\n- permission interfaces for external integration\n- environment-variable and config-file based configuration\n- local samples for testing the library from a backend host and web UI\n\nClaude configuration is represented in the config model, but the Claude provider\nadapter is not implemented yet.\n\n## Direction\n\n`ts-agent` should be a library first. The sample UI is only a local host\napplication that exercises the public library API. Future systems can integrate\nthrough the exported TypeScript interfaces rather than through a product REST\ncontract defined here.\n\nThe project constitution is [CONSTITUTION.md](CONSTITUTION.md). It is the\nhighest-level project policy and must guide future plans, implementations,\nreviews, tests, and documentation.\n\n## Usage\n\nFor host-application integration details, see\n[docs/guides/using-agent-library.md](docs/guides/using-agent-library.md).\nFor CLI usage, see [docs/guides/using-cli.md](docs/guides/using-cli.md).\nFor config keys and meanings, see\n[docs/reference/configuration.md](docs/reference/configuration.md).\n\nAfter the alpha package is published to npm, install it with:\n\n```sh\nnpm install @austinjan/ts-agent@alpha\n```\n\n### Local UI Sample\n\nRun the backend and frontend in separate terminals:\n\n```bash\nnpm run samples:backend\n```\n\n```bash\nnpm run samples:frontend\n```\n\nThen open [http://127.0.0.1:5173/](http://127.0.0.1:5173/). The frontend\nproxies API calls to the backend at `http://localhost:8787`.\n\nThe backend sample lives in `samples/backend/` and imports the public library\nAPI. The frontend sample lives in `samples/frontend/` and demonstrates a chat\ninterface plus reusable UI components for runtime, integration, control, and\nobservability flows.\n\nThe sample backend also exposes `GET /api/providers` so the chat UI can list\navailable providers and the latest sample model choices for each provider.\n\n```ts\nimport {\n  Agent,\n  GeminiProvider,\n  MemoryAuditTrail,\n  FakePermissionPolicy,\n  calculatorSkill,\n  loadAgentConfig,\n} from \"@austinjan/ts-agent\";\n\nconst config = await loadAgentConfig();\nconst gemini = config.providers.gemini;\nif (!gemini?.apiKey) {\n  throw new Error(\"GEMINI_API_KEY is required\");\n}\n\nconst auditTrail = new MemoryAuditTrail();\nconst permissionPolicy = new FakePermissionPolicy();\n\nconst agent = new Agent({\n  provider: new GeminiProvider({\n    apiKey: gemini.apiKey,\n    defaultModel: gemini.model,\n  }),\n  skills: [calculatorSkill],\n  auditTrail,\n  permissionPolicy,\n  config,\n});\n\nconst result = await agent.run({\n  input: \"What is 2 + 3?\",\n});\n\nconsole.log(result.output);\nconsole.log(auditTrail.list());\n```\n\nOpenAI can be selected with the same runtime boundary:\n\n```sh\nOPENAI_API_KEY=... ts-agent --provider openai \"Reply with pong\"\n```\n\n## Configuration\n\nConfiguration will support, in priority order:\n\n1. explicit options passed in code\n2. config file\n3. environment variables\n4. built-in defaults\n\nSee [docs/plan/architecture-plan.md](docs/plan/architecture-plan.md) for the current design.\n\n## Development\n\nThe published or linked binary is `ts-agent`. From this source checkout, use\n`npm run cli --` to pass arguments to that same CLI implementation.\n\n```sh\nnpm install\nnpm run cli -- --help\nnpm run cli -- \"Reply with exactly this single word: pong\"\nnpm run cli -- --provider mock \"hello\"\nnpm run cli -- --audit \"What is 2 + 3?\"\nnpm run typecheck\nnpm run test:smoke\nnpm run test:e2e\nnpm run test:gemini:live\nnpm test\n```\n\n## Status\n\nImplemented first library slice:\n\n- Gemini provider using the official `@google/genai` package\n- OpenAI provider using the official `openai` package\n- provider-agnostic `Agent` runtime with tool-call loop\n- memory audit trail\n- fake permission policy\n- basic tools: `echo`, `add_numbers`, `current_time`\n- basic skills: `calculator`, `utility`\n- env/config loader with JSON-file support and env interpolation\n- CLI for sending a message to the selected provider\n- smoke, end-to-end, and optional live Gemini tests\n\nImplemented sample harness:\n\n- backend sample under `samples/backend/`\n- frontend sample under `samples/frontend/`\n- RESTful sample endpoints for local chat, sessions, attachments, runs,\n  cancellation, provider listing, and resolved configuration inspection\n","readmeFilename":"README.md","_rev":"1-542aa0e2084dbdd3088996aa09de4cfe"}