@harpua/agent-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leath Cooper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @harpua/agent-tools
+
+Framework-agnostic prebuilt [LangChain](https://github.com/langchain-ai/langchainjs)
+tools for agents. Each tool is a plain `tool()` instance, so it drops into any
+LangChain / LangGraph TypeScript app — a `ToolNode`, `createReactAgent`,
+`bindTools`, or your own executor. The package depends only on
+`@langchain/core` and `zod` (both peers): no NestJS, no LangGraph runtime.
+
+## Install
+
+```bash
+pnpm add @harpua/agent-tools
+# peers you almost certainly already have:
+pnpm add @langchain/core zod
+```
+
+## Tools
+
+### `thinkTool(options?)`
+
+The Anthropic-style [think tool](https://www.anthropic.com/engineering/claude-think-tool):
+a no-op scratchpad the model calls to record reasoning between tool calls. The
+handler returns an empty string — nothing executes; the thought is simply logged
+for the model's own benefit. Useful before an irreversible action, when policies
+conflict, or when a tool result is surprising.
+
+```ts
+import { thinkTool } from "@harpua/agent-tools";
+import { ToolNode } from "@langchain/langgraph/prebuilt";
+
+// Vanilla LangGraph: mount it in a ToolNode like any other tool.
+const toolNode = new ToolNode([thinkTool()]);
+```
+
+Tune the when-to-think guidance per domain by overriding the description:
+
+```ts
+const think = thinkTool({
+  description:
+    "Think before cancelling or refunding: confirm the order state and that " +
+    "the customer's request matches policy.",
+});
+```
+
+`options` is validated with zod (`{ description?: string }`, unknown keys
+rejected). The tool's input schema is `z.object({ thought: z.string() })`.
+
+## Using with `@harpua/langgraph`
+
+[`@harpua/langgraph`](../langgraph) accepts these tools directly in a graph's
+`tools` array, mixed freely with its own `@LangGraphTool` provider classes:
+
+```ts
+import { LangGraph, defineEdges, START, TOOLS, END } from "@harpua/langgraph";
+import { thinkTool } from "@harpua/agent-tools";
+
+@LangGraph({ name: "agent", state: AgentState, tools: [OrderTools, thinkTool()] })
+export class AgentGraph {
+  edges = defineEdges<AgentState>([
+    { from: START, to: CallModel },
+    { from: CallModel, to: route<AgentState>(shouldContinue, [TOOLS, END]) },
+    { from: TOOLS, to: CallModel },
+  ]);
+}
+```
+
+The raw tool is mounted into the same `ToolNode` and traced with a
+`langgraph.tool think` span like any DI-bound tool.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { thinkTool } from "./think";
+export type { ThinkToolOptions } from "./think";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.thinkTool = void 0;
+// Framework-agnostic prebuilt LangChain tools for agents. Every tool is exposed
+// as a small `factory(options?)` returning a `tool()` instance — the shape all
+// future tools follow.
+var think_1 = require("./think");
+Object.defineProperty(exports, "thinkTool", { enumerable: true, get: function () { return think_1.thinkTool; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,gFAAgF;AAChF,+EAA+E;AAC/E,uBAAuB;AACvB,iCAAoC;AAA3B,kGAAA,SAAS,OAAA"}

package/dist/think.d.ts

@@ -0,0 +1,28 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+import { z } from "zod";
+/** Options accepted by {@link thinkTool}. Extra keys are rejected. */
+declare const thinkToolOptionsSchema: z.ZodObject<{
+    /** Overrides the default when-to-think description (some domains tune it). */
+    description: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    description?: string | undefined;
+}, {
+    description?: string | undefined;
+}>;
+export type ThinkToolOptions = z.input<typeof thinkToolOptionsSchema>;
+/**
+ * The Anthropic-style `think` tool: a no-op scratchpad an agent calls to record
+ * reasoning between tool calls. The handler returns an empty string, so calling
+ * it executes nothing and produces no output beyond the recorded thought.
+ *
+ * @example
+ * ```ts
+ * import { thinkTool } from "@harpua/agent-tools";
+ * import { ToolNode } from "@langchain/langgraph/prebuilt";
+ *
+ * const toolNode = new ToolNode([thinkTool()]);
+ * ```
+ */
+export declare function thinkTool(options?: ThinkToolOptions): StructuredToolInterface;
+export {};
+//# sourceMappingURL=think.d.ts.map

package/dist/think.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"think.d.ts","sourceRoot":"","sources":["../src/think.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4BxB,sEAAsE;AACtE,QAAA,MAAM,sBAAsB;IAExB,8EAA8E;;;;;;EAGvE,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,uBAAuB,CAO7E"}

package/dist/think.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.thinkTool = thinkTool;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+/**
+ * General-purpose "when to think" guidance, modelled on Anthropic's published
+ * guidance for the think tool. Consumers may override it per domain via
+ * {@link ThinkToolOptions.description}.
+ */
+const DEFAULT_DESCRIPTION = "Use this tool to reason through a problem before acting. It fetches nothing " +
+    "and changes nothing — it only records your reasoning so you can work through " +
+    "it step by step. Reach for it between tool calls: before an irreversible " +
+    "action, when instructions or policies conflict, or when a tool result is " +
+    "surprising and you need to decide what to do next. The thought is recorded " +
+    "for your own benefit; nothing is executed.";
+/**
+ * Input schema for the think tool. The model fills `thought`; the handler is a
+ * no-op, so the field only ever serves as a place to write reasoning.
+ */
+const thinkInputSchema = zod_1.z.object({
+    thought: zod_1.z
+        .string()
+        .describe("Your reasoning. Nothing runs — this is a private scratchpad for working " +
+        "through the problem."),
+});
+/** Options accepted by {@link thinkTool}. Extra keys are rejected. */
+const thinkToolOptionsSchema = zod_1.z
+    .object({
+    /** Overrides the default when-to-think description (some domains tune it). */
+    description: zod_1.z.string().min(1).optional(),
+})
+    .strict();
+/**
+ * The Anthropic-style `think` tool: a no-op scratchpad an agent calls to record
+ * reasoning between tool calls. The handler returns an empty string, so calling
+ * it executes nothing and produces no output beyond the recorded thought.
+ *
+ * @example
+ * ```ts
+ * import { thinkTool } from "@harpua/agent-tools";
+ * import { ToolNode } from "@langchain/langgraph/prebuilt";
+ *
+ * const toolNode = new ToolNode([thinkTool()]);
+ * ```
+ */
+function thinkTool(options) {
+    const { description } = thinkToolOptionsSchema.parse(options ?? {});
+    return (0, tools_1.tool)(() => "", {
+        name: "think",
+        description: description ?? DEFAULT_DESCRIPTION,
+        schema: thinkInputSchema,
+    });
+}
+//# sourceMappingURL=think.js.map

package/dist/think.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"think.js","sourceRoot":"","sources":["../src/think.ts"],"names":[],"mappings":";;AAqDA,8BAOC;AA5DD,iDAA6C;AAE7C,6BAAwB;AAExB;;;;GAIG;AACH,MAAM,mBAAmB,GACvB,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,4CAA4C,CAAC;AAE/C;;;GAGG;AACH,MAAM,gBAAgB,GAAG,OAAC,CAAC,MAAM,CAAC;IAChC,OAAO,EAAE,OAAC;SACP,MAAM,EAAE;SACR,QAAQ,CACP,0EAA0E;QACxE,sBAAsB,CACzB;CACJ,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,sBAAsB,GAAG,OAAC;KAC7B,MAAM,CAAC;IACN,8EAA8E;IAC9E,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ;;;;;;;;;;;;GAYG;AACH,SAAgB,SAAS,CAAC,OAA0B;IAClD,MAAM,EAAE,WAAW,EAAE,GAAG,sBAAsB,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IACpE,OAAO,IAAA,YAAI,EAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACpB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,WAAW,IAAI,mBAAmB;QAC/C,MAAM,EAAE,gBAAgB;KACzB,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@harpua/agent-tools",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Framework-agnostic prebuilt LangChain tools for agents (works with any LangChain/LangGraph app)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IcculusC/harpua.git",
+    "directory": "packages/agent-tools"
+  },
+  "homepage": "https://github.com/IcculusC/harpua/tree/main/packages/agent-tools#readme",
+  "bugs": {
+    "url": "https://github.com/IcculusC/harpua/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": [
+        "ts-jest",
+        {
+          "tsconfig": "<rootDir>/../tsconfig.json"
+        }
+      ]
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node",
+    "testTimeout": 30000
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1",
+    "zod": "^3 || ^4"
+  },
+  "devDependencies": {
+    "@langchain/core": "1.2.1",
+    "@types/jest": "30.0.0",
+    "@types/node": "22.15.30",
+    "eslint": "9.39.4",
+    "jest": "30.4.2",
+    "ts-jest": "29.4.11",
+    "typescript": "5.9.3",
+    "zod": "3.25.76",
+    "@harpua/eslint-config": "0.0.0",
+    "@harpua/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "jest"
+  }
+}