@graphlit/agent-tools 1.0.20260611003

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graphlit
+
+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,129 @@
+# @graphlit/agent-tools
+
+Top-level Graphlit tool factories for TypeScript apps that use `streamAgent()`.
+
+This package gives developers a small set of Graphlit-backed tools they can choose from directly. It does not provide tool discovery, MCP server wrappers, approval middleware, or convenience bundles.
+
+## Install
+
+```bash
+npm install graphlit-client @graphlit/agent-tools
+```
+
+## Basic `streamAgent()` Usage
+
+```typescript
+import { Graphlit } from "graphlit-client";
+import {
+  createInspectContentTool,
+  createRetrieveContentsTool,
+  createWebSearchTool,
+} from "@graphlit/agent-tools";
+
+const client = new Graphlit(
+  process.env.GRAPHLIT_ORGANIZATION_ID!,
+  process.env.GRAPHLIT_ENVIRONMENT_ID!,
+  process.env.GRAPHLIT_JWT_SECRET!,
+);
+
+const retrieveContents = createRetrieveContentsTool(client);
+const inspectContent = createInspectContentTool(client);
+const webSearch = createWebSearchTool(client);
+
+const selectedTools = [retrieveContents, inspectContent, webSearch];
+
+await client.streamAgent(
+  "What customer emails from last week mention onboarding risk?",
+  (event) => {
+    // Stream events to your UI.
+  },
+  undefined,
+  undefined,
+  selectedTools.map((tool) => tool.tool),
+  Object.fromEntries(selectedTools.map((tool) => [tool.tool.name, tool.handler])),
+  {
+    maxToolRounds: 8,
+  },
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  [
+    "Use retrieve_contents before answering questions that depend on ingested Graphlit content.",
+    "Use inspect_content when a retrieved result needs fuller text before making a source-backed claim.",
+    "If retrieved evidence is weak or missing, say so plainly.",
+  ].join(" "),
+);
+```
+
+## Realistic Retrieval Examples
+
+`retrieve_contents` supports both semantic retrieval and filter-only content lookup.
+
+For a model prompt such as “show me all emails from last week,” the tool can be called without a text search:
+
+```typescript
+await retrieveContents.handler({
+  type: "EMAIL",
+  inLast: "P7D",
+  limit: 25,
+});
+```
+
+For RAG over specific content text, pass `search`:
+
+```typescript
+await retrieveContents.handler({
+  search: "onboarding risk renewal blocker",
+  type: "EMAIL",
+  inLast: "P30D",
+  limit: 10,
+});
+```
+
+For upcoming calendar context:
+
+```typescript
+await retrieveContents.handler({
+  type: "EVENT",
+  inNext: "P7D",
+  limit: 20,
+});
+```
+
+When answer-critical evidence needs more context, inspect the `contents://...` reference returned by retrieval:
+
+```typescript
+await inspectContent.handler({
+  resourceUri: "contents://content-id-from-retrieve-contents",
+  mode: "markdown",
+});
+```
+
+## Tools
+
+| Factory | Tool name | SDK operation |
+| --- | --- | --- |
+| `createRetrieveContentsTool()` | `retrieve_contents` | `retrieveSources`, `lookupContents`, `queryContents` |
+| `createInspectContentTool()` | `inspect_content` | `getContent` |
+| `createWebSearchTool()` | `web_search` | `searchWeb` |
+| `createIngestUrlTool()` | `ingest_url` | `ingestUri` |
+| `createWaitContentDoneTool()` | `wait_content_done` | `isContentDone` |
+
+Each factory returns:
+
+```typescript
+type GraphlitAgentTool = {
+  tool: Types.ToolDefinitionInput;
+  handler: NonNullable<Parameters<Graphlit["streamAgent"]>[5]>[string];
+};
+```
+
+## Notes
+
+- Run these tools server-side with Graphlit credentials.
+- Tool schemas are authored with Zod and converted to Graphlit `ToolDefinitionInput`.
+- Public options reuse `graphlit-client` SDK types where possible, including `Types.ContentFilter`, `Types.EntityReferenceInput`, `Types.RetrievalStrategyInput`, and `Types.RerankingStrategyInput`.
+- Returned retrieval results include `contents://...` resource URIs for UI source rendering and follow-up inspection.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ContentReference, GraphlitAgentTool, GraphlitClient, GraphlitToolHandler, StreamAgentArtifactCollector, StreamAgentToolHandler, StreamAgentToolHandlers, } from "./types.js";
+export { createIngestUrlTool, IngestUrlInputSchema, type IngestUrlArgs, type IngestUrlResult, type IngestUrlToolOptions, } from "./tools/ingest-url.js";
+export { createInspectContentTool, InspectContentInputSchema, type InspectContentArgs, type InspectContentResult, type InspectContentToolOptions, } from "./tools/inspect-content.js";
+export { createRetrieveContentsTool, RetrieveContentsInputSchema, type RetrieveContentsArgs, type RetrievedContentResult, type RetrieveContentsResult, type RetrieveContentsToolOptions, } from "./tools/retrieve-contents.js";
+export { createWaitContentDoneTool, WaitContentDoneInputSchema, type WaitContentDoneArgs, type WaitContentDoneResult, type WaitContentDoneToolOptions, } from "./tools/wait-content-done.js";
+export { createWebSearchTool, WebSearchInputSchema, type WebSearchArgs, type WebSearchToolOptions, type WebSearchToolResult, } from "./tools/web-search.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createIngestUrlTool, IngestUrlInputSchema, } from "./tools/ingest-url.js";
+export { createInspectContentTool, InspectContentInputSchema, } from "./tools/inspect-content.js";
+export { createRetrieveContentsTool, RetrieveContentsInputSchema, } from "./tools/retrieve-contents.js";
+export { createWaitContentDoneTool, WaitContentDoneInputSchema, } from "./tools/wait-content-done.js";
+export { createWebSearchTool, WebSearchInputSchema, } from "./tools/web-search.js";

package/dist/tools/ingest-url.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import type { ContentReference, GraphlitAgentTool, GraphlitClient } from "../types.js";
+import type { Types } from "graphlit-client";
+export declare const IngestUrlInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    waitForCompletion: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    name?: string | undefined;
+    waitForCompletion?: boolean | undefined;
+}, {
+    url: string;
+    name?: string | undefined;
+    waitForCompletion?: boolean | undefined;
+}>;
+export type IngestUrlArgs = z.infer<typeof IngestUrlInputSchema>;
+export interface IngestUrlToolOptions {
+    collections?: ContentReference[];
+    workflow?: Types.EntityReferenceInput;
+    defaultWaitForCompletion?: boolean;
+    correlationId?: string;
+}
+export interface IngestUrlResult {
+    id: string;
+    resourceUri: string;
+    name: string;
+    uri?: string | null;
+    state?: string | null;
+    type?: string | null;
+    fileType?: string | null;
+    mimeType?: string | null;
+    waitForCompletion: boolean;
+}
+export declare function createIngestUrlTool(client: GraphlitClient, options?: IngestUrlToolOptions): GraphlitAgentTool<IngestUrlArgs, IngestUrlResult>;

package/dist/tools/ingest-url.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { throwIfAborted } from "../utils/abort.js";
+import { contentName, scalarToString, toContentResourceUri } from "../utils/content.js";
+import { createToolDefinition } from "../utils/schema.js";
+export const IngestUrlInputSchema = z.object({
+    url: z.string().trim().url().describe("Public URL to ingest into Graphlit."),
+    name: z.string().trim().min(1).optional().describe("Optional content name."),
+    waitForCompletion: z
+        .boolean()
+        .optional()
+        .describe("Whether Graphlit should process the URL synchronously."),
+});
+export function createIngestUrlTool(client, options = {}) {
+    return {
+        tool: createToolDefinition("ingest_url", "Ingest a public URL into Graphlit so it can be retrieved by later agent turns.", IngestUrlInputSchema),
+        handler: async (rawArgs, artifacts, abortSignal) => {
+            throwIfAborted(abortSignal);
+            const args = IngestUrlInputSchema.parse(rawArgs);
+            const waitForCompletion = args.waitForCompletion ?? options.defaultWaitForCompletion ?? false;
+            const response = await client.ingestUri(args.url, args.name, undefined, undefined, waitForCompletion, options.workflow, options.collections, undefined, options.correlationId);
+            const content = response.ingestUri;
+            if (!content) {
+                throw new Error(`Failed to ingest URL: ${args.url}`);
+            }
+            artifacts?.addPending(Promise.resolve({ id: content.id }));
+            return {
+                id: content.id,
+                resourceUri: toContentResourceUri(content.id) ?? `contents://${content.id}`,
+                name: contentName(content),
+                uri: scalarToString(content.uri),
+                state: content.state,
+                type: content.type,
+                fileType: content.fileType,
+                mimeType: content.mimeType,
+                waitForCompletion,
+            };
+        },
+    };
+}

package/dist/tools/inspect-content.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import type { GraphlitAgentTool, GraphlitClient } from "../types.js";
+export declare const InspectContentInputSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    resourceUri: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<["auto", "summary", "markdown"]>>;
+    maxTextLength: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    resourceUri?: string | undefined;
+    mode?: "auto" | "summary" | "markdown" | undefined;
+    maxTextLength?: number | undefined;
+}, {
+    id?: string | undefined;
+    resourceUri?: string | undefined;
+    mode?: "auto" | "summary" | "markdown" | undefined;
+    maxTextLength?: number | undefined;
+}>;
+export type InspectContentArgs = z.infer<typeof InspectContentInputSchema>;
+export interface InspectContentToolOptions {
+    maxTextLength?: number;
+}
+export interface InspectContentResult {
+    id: string;
+    resourceUri: string;
+    name: string;
+    uri?: string | null;
+    type?: string | null;
+    fileType?: string | null;
+    mimeType?: string | null;
+    mode: "auto" | "summary" | "markdown";
+    text: string;
+    truncated: boolean;
+}
+export declare function createInspectContentTool(client: GraphlitClient, options?: InspectContentToolOptions): GraphlitAgentTool<InspectContentArgs, InspectContentResult>;

package/dist/tools/inspect-content.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { throwIfAborted } from "../utils/abort.js";
+import { contentName, parseContentResourceUri, scalarToString, toContentResourceUri, } from "../utils/content.js";
+import { createToolDefinition } from "../utils/schema.js";
+import { truncateText } from "../utils/text.js";
+const DEFAULT_MAX_TEXT_LENGTH = 12_000;
+export const InspectContentInputSchema = z.object({
+    id: z.string().trim().min(1).optional().describe("Graphlit content ID."),
+    resourceUri: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Graphlit content resource URI, such as contents://content-id."),
+    mode: z
+        .enum(["auto", "summary", "markdown"])
+        .optional()
+        .describe("Text to return. Defaults to auto."),
+    maxTextLength: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Maximum text length to return."),
+});
+function resolveContentId(args) {
+    const id = args.id ?? parseContentResourceUri(args.resourceUri);
+    if (!id) {
+        throw new Error("Provide either id or resourceUri.");
+    }
+    return id;
+}
+export function createInspectContentTool(client, options = {}) {
+    return {
+        tool: createToolDefinition("inspect_content", "Inspect one Graphlit content item returned by retrieve_contents, using its id or contents:// resource URI.", InspectContentInputSchema),
+        handler: async (rawArgs, _artifacts, abortSignal) => {
+            throwIfAborted(abortSignal);
+            const args = InspectContentInputSchema.parse(rawArgs);
+            const id = resolveContentId(args);
+            const response = await client.getContent(id);
+            const content = response.content;
+            if (!content) {
+                throw new Error(`Content not found: ${id}`);
+            }
+            const mode = args.mode ?? "auto";
+            const maxTextLength = args.maxTextLength ?? options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH;
+            const textSource = mode === "summary"
+                ? (content.customSummary ??
+                    content.summary ??
+                    content.snippet ??
+                    content.description)
+                : mode === "markdown"
+                    ? (content.markdown ??
+                        content.customSummary ??
+                        content.summary ??
+                        content.snippet ??
+                        content.description)
+                    : (content.markdown ??
+                        content.customSummary ??
+                        content.summary ??
+                        content.snippet ??
+                        content.description);
+            const { text, truncated } = truncateText(textSource ?? "", maxTextLength);
+            return {
+                id: content.id,
+                resourceUri: toContentResourceUri(content.id) ?? `contents://${content.id}`,
+                name: contentName(content),
+                uri: scalarToString(content.uri),
+                type: content.type,
+                fileType: content.fileType,
+                mimeType: content.mimeType,
+                mode,
+                text,
+                truncated,
+            };
+        },
+    };
+}

package/dist/tools/retrieve-contents.d.ts

@@ -0,0 +1,68 @@
+import { Types } from "graphlit-client";
+import { z } from "zod";
+import type { ContentReference, GraphlitAgentTool, GraphlitClient } from "../types.js";
+export declare const RetrieveContentsInputSchema: z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    inLast: z.ZodOptional<z.ZodString>;
+    inNext: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodNativeEnum<typeof Types.ContentTypes>>;
+    fileType: z.ZodOptional<z.ZodNativeEnum<typeof Types.FileTypes>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type?: Types.ContentTypes | undefined;
+    fileType?: Types.FileTypes | undefined;
+    search?: string | undefined;
+    inLast?: string | undefined;
+    inNext?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, {
+    type?: Types.ContentTypes | undefined;
+    fileType?: Types.FileTypes | undefined;
+    search?: string | undefined;
+    inLast?: string | undefined;
+    inNext?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
+export type RetrieveContentsArgs = z.infer<typeof RetrieveContentsInputSchema>;
+export interface RetrieveContentsToolOptions {
+    collectionId?: string;
+    collections?: ContentReference[];
+    baseFilter?: Types.ContentFilter;
+    defaultLimit?: number;
+    maxLimit?: number;
+    maxTextLength?: number;
+    searchType?: Types.SearchTypes;
+    retrievalStrategy?: Types.RetrievalStrategyInput;
+    rerankingStrategy?: Types.RerankingStrategyInput;
+    correlationId?: string;
+}
+export interface RetrievedContentResult {
+    id: string;
+    resourceUri: string;
+    name: string;
+    uri?: string | null;
+    type?: Types.ContentTypes | null;
+    fileType?: Types.FileTypes | null;
+    mimeType?: string | null;
+    creationDate?: string | null;
+    originalDate?: string | null;
+    relevance?: number | null;
+    text: string;
+    truncated: boolean;
+    source?: {
+        metadata?: string | null;
+        pageNumber?: number | null;
+        frameNumber?: number | null;
+        startTime?: string | null;
+        endTime?: string | null;
+    };
+}
+export interface RetrieveContentsResult {
+    search: string | null;
+    collectionIds: string[];
+    results: RetrievedContentResult[];
+}
+export declare function createRetrieveContentsTool(client: GraphlitClient, options?: RetrieveContentsToolOptions): GraphlitAgentTool<RetrieveContentsArgs, RetrieveContentsResult>;

package/dist/tools/retrieve-contents.js

@@ -0,0 +1,170 @@
+import { Types } from "graphlit-client";
+import { z } from "zod";
+import { throwIfAborted } from "../utils/abort.js";
+import { clampInteger } from "../utils/clamp.js";
+import { collectionIds, contentName, normalizeCollections, scalarToString, toContentResourceUri, } from "../utils/content.js";
+import { createToolDefinition } from "../utils/schema.js";
+import { truncateText } from "../utils/text.js";
+const DEFAULT_LIMIT = 10;
+const DEFAULT_MAX_LIMIT = 100;
+const DEFAULT_MAX_TEXT_LENGTH = 4_000;
+export const RetrieveContentsInputSchema = z.object({
+    search: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Specific text to match against content. Omit for filter-only lookups like all emails in the last week."),
+    inLast: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Backward-looking original-date filter as an ISO 8601 duration, such as P7D for the last 7 days."),
+    inNext: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Forward-looking original-date filter as an ISO 8601 duration, such as P3D for the next 3 days."),
+    type: z
+        .nativeEnum(Types.ContentTypes)
+        .optional()
+        .describe("Graphlit content type, such as EMAIL, EVENT, FILE, PAGE, or TEXT."),
+    fileType: z
+        .nativeEnum(Types.FileTypes)
+        .optional()
+        .describe("Graphlit file type, such as DOCUMENT, IMAGE, AUDIO, or VIDEO."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Number of results to skip for filter-only pagination."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(DEFAULT_MAX_LIMIT)
+        .optional()
+        .describe("Maximum number of results. Defaults to 10."),
+});
+function buildFilter(args, options, limit) {
+    const collections = normalizeCollections(options);
+    return {
+        ...options.baseFilter,
+        searchType: args.search
+            ? (options.searchType ?? options.baseFilter?.searchType ?? Types.SearchTypes.Hybrid)
+            : options.baseFilter?.searchType,
+        disableInheritance: options.baseFilter?.disableInheritance ?? true,
+        collections: collections ?? options.baseFilter?.collections,
+        inLast: args.inLast ?? options.baseFilter?.inLast,
+        inNext: args.inNext ?? options.baseFilter?.inNext,
+        types: args.type ? [args.type] : options.baseFilter?.types,
+        fileTypes: args.fileType ? [args.fileType] : options.baseFilter?.fileTypes,
+        offset: args.search ? options.baseFilter?.offset : (args.offset ?? options.baseFilter?.offset),
+        limit,
+    };
+}
+function mapContentMetadata(content) {
+    return {
+        id: content.id,
+        resourceUri: toContentResourceUri(content.id) ?? `contents://${content.id}`,
+        name: contentName(content),
+        uri: scalarToString(content.uri),
+        type: content.type,
+        fileType: content.fileType,
+        mimeType: content.mimeType,
+        creationDate: scalarToString(content.creationDate),
+        originalDate: scalarToString(content.originalDate),
+    };
+}
+function summarizeContent(content, maxTextLength) {
+    return truncateText(content.customSummary ??
+        content.summary ??
+        content.snippet ??
+        content.description ??
+        "", maxTextLength);
+}
+function mapQueryContent(content, maxTextLength) {
+    const { text, truncated } = summarizeContent(content, maxTextLength);
+    return {
+        ...mapContentMetadata(content),
+        relevance: content.relevance,
+        text,
+        truncated,
+    };
+}
+function mapRetrievedSource(source, content, maxTextLength) {
+    const fallback = summarizeContent(content, maxTextLength);
+    const sourceText = truncateText(source.text ?? fallback.text, maxTextLength);
+    return {
+        ...mapContentMetadata(content),
+        relevance: source.relevance,
+        text: sourceText.text,
+        truncated: sourceText.truncated || fallback.truncated,
+        source: {
+            metadata: source.metadata,
+            pageNumber: source.pageNumber,
+            frameNumber: source.frameNumber,
+            startTime: scalarToString(source.startTime),
+            endTime: scalarToString(source.endTime),
+        },
+    };
+}
+export function createRetrieveContentsTool(client, options = {}) {
+    const defaultLimit = options.defaultLimit ?? DEFAULT_LIMIT;
+    const maxLimit = options.maxLimit ?? DEFAULT_MAX_LIMIT;
+    const maxTextLength = options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH;
+    return {
+        tool: createToolDefinition("retrieve_contents", "Retrieve Graphlit-ingested content for RAG. Use search for text matching, or omit search for filter-only requests such as all emails in the last week.", RetrieveContentsInputSchema),
+        handler: async (rawArgs, _artifacts, abortSignal) => {
+            throwIfAborted(abortSignal);
+            const args = RetrieveContentsInputSchema.parse(rawArgs);
+            const limit = clampInteger(args.limit, defaultLimit, 1, maxLimit);
+            const filter = buildFilter(args, options, limit);
+            const collections = normalizeCollections(options);
+            if (!args.search) {
+                const response = await client.queryContents(filter);
+                const results = response.contents?.results
+                    ?.filter((content) => content != null)
+                    .map((content) => mapQueryContent(content, maxTextLength)) ?? [];
+                return {
+                    search: null,
+                    collectionIds: collectionIds(collections),
+                    results,
+                };
+            }
+            const retrievalStrategy = options.retrievalStrategy ?? {
+                type: Types.RetrievalStrategyTypes.Section,
+                contentLimit: limit,
+                disableFallback: true,
+            };
+            const rerankingStrategy = options.rerankingStrategy ?? {
+                serviceType: Types.RerankingModelServiceTypes.Cohere,
+            };
+            const retrieved = await client.retrieveSources(args.search, filter, undefined, retrievalStrategy, rerankingStrategy, options.correlationId);
+            const sources = retrieved.retrieveSources?.results?.filter((source) => Boolean(source?.content?.id)) ?? [];
+            const contentIds = [
+                ...new Set(sources.map((source) => source.content.id)),
+            ];
+            const lookup = contentIds.length > 0 ? await client.lookupContents(contentIds) : undefined;
+            const contentMap = new Map((lookup?.lookupContents?.results ?? [])
+                .filter((content) => content != null)
+                .map((content) => [content.id, content]));
+            const results = sources
+                .map((source) => {
+                const content = contentMap.get(source.content.id);
+                return content
+                    ? mapRetrievedSource(source, content, maxTextLength)
+                    : null;
+            })
+                .filter((result) => result != null);
+            return {
+                search: args.search,
+                collectionIds: collectionIds(collections),
+                results,
+            };
+        },
+    };
+}

package/dist/tools/wait-content-done.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { GraphlitAgentTool, GraphlitClient } from "../types.js";
+export declare const WaitContentDoneInputSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    resourceUri: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    resourceUri?: string | undefined;
+    timeoutMs?: number | undefined;
+    pollIntervalMs?: number | undefined;
+}, {
+    id?: string | undefined;
+    resourceUri?: string | undefined;
+    timeoutMs?: number | undefined;
+    pollIntervalMs?: number | undefined;
+}>;
+export type WaitContentDoneArgs = z.infer<typeof WaitContentDoneInputSchema>;
+export interface WaitContentDoneToolOptions {
+    defaultTimeoutMs?: number;
+    defaultPollIntervalMs?: number;
+}
+export interface WaitContentDoneResult {
+    id: string;
+    done: boolean;
+    attempts: number;
+    elapsedMs: number;
+}
+export declare function createWaitContentDoneTool(client: GraphlitClient, options?: WaitContentDoneToolOptions): GraphlitAgentTool<WaitContentDoneArgs, WaitContentDoneResult>;

package/dist/tools/wait-content-done.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { delay, throwIfAborted } from "../utils/abort.js";
+import { clampInteger } from "../utils/clamp.js";
+import { parseContentResourceUri } from "../utils/content.js";
+import { createToolDefinition } from "../utils/schema.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const MIN_POLL_INTERVAL_MS = 250;
+const MAX_TIMEOUT_MS = 300_000;
+export const WaitContentDoneInputSchema = z.object({
+    id: z.string().trim().min(1).optional().describe("Graphlit content ID."),
+    resourceUri: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Graphlit content resource URI, such as contents://content-id."),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Maximum time to wait in milliseconds."),
+    pollIntervalMs: z
+        .number()
+        .int()
+        .min(MIN_POLL_INTERVAL_MS)
+        .optional()
+        .describe("Polling interval in milliseconds."),
+});
+function resolveContentId(args) {
+    const id = args.id ?? parseContentResourceUri(args.resourceUri);
+    if (!id) {
+        throw new Error("Provide either id or resourceUri.");
+    }
+    return id;
+}
+export function createWaitContentDoneTool(client, options = {}) {
+    return {
+        tool: createToolDefinition("wait_content_done", "Wait until a Graphlit content item has finished processing.", WaitContentDoneInputSchema),
+        handler: async (rawArgs, _artifacts, abortSignal) => {
+            throwIfAborted(abortSignal);
+            const args = WaitContentDoneInputSchema.parse(rawArgs);
+            const id = resolveContentId(args);
+            const timeoutMs = clampInteger(args.timeoutMs, options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS);
+            const pollIntervalMs = clampInteger(args.pollIntervalMs, options.defaultPollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS, timeoutMs);
+            const startedAt = Date.now();
+            let attempts = 0;
+            while (Date.now() - startedAt <= timeoutMs) {
+                throwIfAborted(abortSignal);
+                attempts += 1;
+                const response = await client.isContentDone(id);
+                const done = response.isContentDone?.result === true;
+                if (done) {
+                    return {
+                        id,
+                        done: true,
+                        attempts,
+                        elapsedMs: Date.now() - startedAt,
+                    };
+                }
+                await delay(pollIntervalMs, abortSignal);
+            }
+            return {
+                id,
+                done: false,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+            };
+        },
+    };
+}

package/dist/tools/web-search.d.ts

@@ -0,0 +1,34 @@
+import { Types } from "graphlit-client";
+import { z } from "zod";
+import type { GraphlitAgentTool, GraphlitClient } from "../types.js";
+export declare const WebSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    searchService: z.ZodOptional<z.ZodNativeEnum<typeof Types.SearchServiceTypes>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit?: number | undefined;
+    searchService?: Types.SearchServiceTypes | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+    searchService?: Types.SearchServiceTypes | undefined;
+}>;
+export type WebSearchArgs = z.infer<typeof WebSearchInputSchema>;
+export interface WebSearchToolOptions {
+    defaultSearchService?: Types.SearchServiceTypes;
+    defaultLimit?: number;
+    maxLimit?: number;
+    correlationId?: string;
+}
+export interface WebSearchToolResult {
+    query: string;
+    searchService: Types.SearchServiceTypes;
+    results: Array<{
+        title?: string | null;
+        uri?: string | null;
+        text?: string | null;
+        score?: number | null;
+    }>;
+}
+export declare function createWebSearchTool(client: GraphlitClient, options?: WebSearchToolOptions): GraphlitAgentTool<WebSearchArgs, WebSearchToolResult>;

package/dist/tools/web-search.js

@@ -0,0 +1,52 @@
+import { Types } from "graphlit-client";
+import { z } from "zod";
+import { throwIfAborted } from "../utils/abort.js";
+import { clampInteger } from "../utils/clamp.js";
+import { scalarToString } from "../utils/content.js";
+import { createToolDefinition } from "../utils/schema.js";
+const DEFAULT_LIMIT = 10;
+const DEFAULT_MAX_LIMIT = 20;
+export const WebSearchInputSchema = z.object({
+    query: z.string().trim().min(1).describe("Search query."),
+    searchService: z
+        .nativeEnum(Types.SearchServiceTypes)
+        .optional()
+        .describe("Search service. Defaults to PARALLEL."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(DEFAULT_MAX_LIMIT)
+        .optional()
+        .describe("Maximum results. Defaults to 10."),
+});
+function mapWebSearchResult(result) {
+    return {
+        title: result.title,
+        uri: scalarToString(result.uri),
+        text: result.text,
+        score: result.score,
+    };
+}
+export function createWebSearchTool(client, options = {}) {
+    const defaultSearchService = options.defaultSearchService ?? Types.SearchServiceTypes.Parallel;
+    const defaultLimit = options.defaultLimit ?? DEFAULT_LIMIT;
+    const maxLimit = options.maxLimit ?? DEFAULT_MAX_LIMIT;
+    return {
+        tool: createToolDefinition("web_search", "Search the public web for current information. Returns URLs, titles, and snippets; it does not ingest results.", WebSearchInputSchema),
+        handler: async (rawArgs, _artifacts, abortSignal) => {
+            throwIfAborted(abortSignal);
+            const args = WebSearchInputSchema.parse(rawArgs);
+            const searchService = args.searchService ?? defaultSearchService;
+            const limit = clampInteger(args.limit, defaultLimit, 1, maxLimit);
+            const response = await client.searchWeb(args.query, searchService, limit, options.correlationId);
+            return {
+                query: args.query,
+                searchService,
+                results: response.searchWeb?.results
+                    ?.filter((result) => result != null)
+                    .map(mapWebSearchResult) ?? [],
+            };
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+import type { Graphlit, Types } from "graphlit-client";
+export type GraphlitClient = Graphlit;
+export type StreamAgentToolHandlers = NonNullable<Parameters<Graphlit["streamAgent"]>[5]>;
+export type StreamAgentToolHandler = StreamAgentToolHandlers[string];
+export type StreamAgentArtifactCollector = Parameters<StreamAgentToolHandler>[1];
+export type GraphlitToolHandler<TArgs = unknown, TResult = unknown> = (args: TArgs, artifacts?: StreamAgentArtifactCollector, abortSignal?: AbortSignal) => Promise<TResult>;
+export interface GraphlitAgentTool<TArgs = unknown, TResult = unknown> {
+    tool: Types.ToolDefinitionInput;
+    handler: GraphlitToolHandler<TArgs, TResult>;
+}
+export type ContentReference = Types.EntityReferenceInput;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/abort.d.ts

@@ -0,0 +1,2 @@
+export declare function throwIfAborted(abortSignal?: AbortSignal): void;
+export declare function delay(ms: number, abortSignal?: AbortSignal): Promise<void>;

package/dist/utils/abort.js

@@ -0,0 +1,26 @@
+export function throwIfAborted(abortSignal) {
+    if (abortSignal?.aborted) {
+        throw new Error("Operation aborted");
+    }
+}
+export function delay(ms, abortSignal) {
+    return new Promise((resolve, reject) => {
+        if (abortSignal?.aborted) {
+            reject(new Error("Operation aborted"));
+            return;
+        }
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            cleanup();
+            reject(new Error("Operation aborted"));
+        };
+        const cleanup = () => {
+            abortSignal?.removeEventListener("abort", onAbort);
+        };
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/utils/clamp.d.ts

@@ -0,0 +1 @@
+export declare function clampInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number;

package/dist/utils/clamp.js

@@ -0,0 +1,4 @@
+export function clampInteger(value, fallback, minimum, maximum) {
+    const input = value === undefined || !Number.isFinite(value) ? fallback : value;
+    return Math.min(Math.max(Math.floor(input), minimum), maximum);
+}

package/dist/utils/content.d.ts

@@ -0,0 +1,14 @@
+import type { Types } from "graphlit-client";
+import type { ContentReference } from "../types.js";
+export declare function toContentResourceUri(id: string | null | undefined): string | null;
+export declare function parseContentResourceUri(uri: string | null | undefined): string | null;
+export declare function contentName(content: {
+    fileName?: string | null;
+    name?: string | null;
+}): string;
+export declare function normalizeCollections(options: {
+    collectionId?: string;
+    collections?: ContentReference[];
+}): Types.EntityReferenceInput[] | undefined;
+export declare function collectionIds(collections: Types.EntityReferenceInput[] | undefined): string[];
+export declare function scalarToString(value: unknown): string | null;

package/dist/utils/content.js

@@ -0,0 +1,27 @@
+export function toContentResourceUri(id) {
+    return id ? `contents://${id}` : null;
+}
+export function parseContentResourceUri(uri) {
+    if (!uri) {
+        return null;
+    }
+    return uri.startsWith("contents://") ? uri.slice("contents://".length) : null;
+}
+export function contentName(content) {
+    return content.fileName || content.name || "Untitled content";
+}
+export function normalizeCollections(options) {
+    if (options.collections?.length) {
+        return options.collections.map(({ id }) => ({ id }));
+    }
+    return options.collectionId ? [{ id: options.collectionId }] : undefined;
+}
+export function collectionIds(collections) {
+    return collections?.map((collection) => collection.id).filter(Boolean) ?? [];
+}
+export function scalarToString(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return typeof value === "string" ? value : String(value);
+}

package/dist/utils/schema.d.ts

@@ -0,0 +1,4 @@
+import type { Types } from "graphlit-client";
+import { z } from "zod";
+export declare function toToolSchema(schema: z.ZodTypeAny): string;
+export declare function createToolDefinition(name: string, description: string, schema: z.ZodTypeAny): Types.ToolDefinitionInput;

package/dist/utils/schema.js

@@ -0,0 +1,32 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+function stripUnsupportedSchemaFields(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripUnsupportedSchemaFields);
+    }
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const input = value;
+    const output = {};
+    for (const [key, nestedValue] of Object.entries(input)) {
+        if (key === "$schema" || key === "definitions" || key === "$defs") {
+            continue;
+        }
+        output[key] = stripUnsupportedSchemaFields(nestedValue);
+    }
+    return output;
+}
+export function toToolSchema(schema) {
+    const jsonSchema = zodToJsonSchema(schema, {
+        $refStrategy: "none",
+        target: "jsonSchema7",
+    });
+    return JSON.stringify(stripUnsupportedSchemaFields(jsonSchema));
+}
+export function createToolDefinition(name, description, schema) {
+    return {
+        name,
+        description,
+        schema: toToolSchema(schema),
+    };
+}

package/dist/utils/text.d.ts

@@ -0,0 +1,4 @@
+export declare function truncateText(text: string | null | undefined, maxLength: number): {
+    text: string;
+    truncated: boolean;
+};

package/dist/utils/text.js

@@ -0,0 +1,10 @@
+export function truncateText(text, maxLength) {
+    const value = text?.trim() ?? "";
+    if (!value || value.length <= maxLength) {
+        return { text: value, truncated: false };
+    }
+    return {
+        text: `${value.slice(0, Math.max(0, maxLength - 3))}...`,
+        truncated: true,
+    };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@graphlit/agent-tools",
+  "version": "1.0.20260611003",
+  "private": false,
+  "description": "Top-level Graphlit tool factories for TypeScript streamAgent applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphlit/graphlit-agent-tools.git"
+  },
+  "keywords": [
+    "Graphlit",
+    "agents",
+    "tools",
+    "RAG",
+    "streamAgent",
+    "LLM"
+  ],
+  "author": "Unstruk Data Inc.",
+  "contributors": [
+    "Kirk Marple (https://github.com/kirk-marple)"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "peerDependencies": {
+    "graphlit-client": ">=1.0.20260609001"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "graphlit-client": "^1.0.20260609001",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}