@alint-js/agent 0.0.4

package/README.md

@@ -0,0 +1,59 @@
+# `@alint-js/agent`
+
+> [!IMPORTANT]
+> This package is a WIP. APIs may be subject to major changes.
+
+**BYOA** — **B**ring **Y**our **O**wn **A**gent.
+
+The agent-agnostic contract for tool-using alint rules. Optional layer on top of
+`@alint-js/core`. Install only when a rule needs an agent.
+
+## What it does
+
+Defines the small contract that lets a rule run a multi-step tool loop without
+building an LLM SDK, while staying free to swap the underlying agent framework:
+
+## Concepts
+
+### AgentAdapter
+
+`(request) => Promise<{ answer, usage }>`. A rule hands a request (instructions, prompt, model, tools) to an adapter; the adapter runs the loop.
+
+### AgentTool
+
+A framework-free tool shape (`name`, `description`, JSON Schema `parameters`, `execute`). Each adapter translates it to its framework's tool format.
+
+### defineTool
+
+Identity helper for authoring tools with a checked shape.
+
+## How to use
+
+Write tools with `defineTool`, then pass them plus an adapter to your rule:
+
+```ts
+import type { AgentAdapter } from '@alint-js/agent'
+
+import { defineTool } from '@alint-js/agent'
+
+const grep = defineTool({
+  description: 'Search the repo.',
+  execute: async input => /* ... */ '',
+  name: 'grep',
+  parameters: { properties: { query: { type: 'string' } }, required: ['query'], type: 'object' },
+})
+
+async function run(adapter: AgentAdapter) {
+  return adapter({ instructions: '...', model, prompt: '...', tools: [grep] })
+}
+```
+
+The adapter itself comes from a framework package (e.g. an adapter for Apeira agent or Pi agent) or your own function of type `AgentAdapter`.
+
+## When to use
+
+- You run rules that need to explore (read files, search, call tools) across multiple steps before reporting, not single one-shot "judge" rules.
+
+## When not to use
+
+- You run one-shot, no-tool "judge" rules. They don't need an agent. Keep them on the plain `@alint-js/core` rule DSL. If you don't write tool-using rules, you may not need this.

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import { ResolvedModel } from "@alint-js/core";
+
+//#region src/index.d.ts
+type AgentAdapter = (request: AgentRequest) => Promise<AgentResult>;
+interface AgentRequest {
+  instructions: string;
+  model: ResolvedModel;
+  prompt: string;
+  signal?: AbortSignal;
+  tools: AgentTool[];
+}
+interface AgentResult {
+  answer: string;
+  usage?: AgentUsage;
+}
+/** Agent-agnostic tool definition. Each adapter translates it to its framework's tool format. */
+interface AgentTool {
+  description: string;
+  execute: (input: unknown) => Promise<unknown> | unknown;
+  name: string;
+  parameters: Record<string, unknown>;
+}
+interface AgentUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+declare function defineTool(tool: AgentTool): AgentTool;
+//#endregion
+export { AgentAdapter, AgentRequest, AgentResult, AgentTool, AgentUsage, defineTool };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+//#region src/index.ts
+function defineTool(tool) {
+	return tool;
+}
+//#endregion
+export { defineTool };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@alint-js/agent",
+  "type": "module",
+  "version": "0.0.4",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@alint-js/core": "0.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  }
+}