@xfey/tutti 0.1.0

package/dist/server-shell/http/host-tunnel.js

@@ -0,0 +1,154 @@
+import { TRUSTED_RELAY_METADATA_REQUEST_HEADER, } from "../session/relay-session-context.js";
+function decodeRequestBody(bodyBase64) {
+    if (bodyBase64 === undefined) {
+        return undefined;
+    }
+    return Buffer.from(bodyBase64, "base64");
+}
+function injectHeaders(request) {
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (name.toLowerCase() === TRUSTED_RELAY_METADATA_REQUEST_HEADER) {
+            continue;
+        }
+        headers[name] = typeof value === "string" ? value : Array.from(value);
+    }
+    return headers;
+}
+function responseHeaders(headers) {
+    const relayHeaders = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        relayHeaders[name] = typeof value === "number" ? String(value) : value;
+    }
+    return relayHeaders;
+}
+function responseBodyBuffer(response) {
+    const rawPayload = response.rawPayload;
+    if (Buffer.isBuffer(rawPayload)) {
+        return rawPayload;
+    }
+    if (rawPayload instanceof Uint8Array) {
+        return Buffer.from(rawPayload);
+    }
+    if (rawPayload instanceof ArrayBuffer) {
+        return Buffer.from(rawPayload);
+    }
+    return Buffer.from(response.body, "utf8");
+}
+function fetchResponseHeaders(headers) {
+    const relayHeaders = {};
+    headers.forEach((value, name) => {
+        relayHeaders[name] = value;
+    });
+    return relayHeaders;
+}
+function fetchRequestHeaders(headers) {
+    const fetchHeaders = {};
+    for (const [name, value] of Object.entries(headers)) {
+        fetchHeaders[name] = typeof value === "string" ? value : value.join(", ");
+    }
+    return fetchHeaders;
+}
+function toInjectMethod(method) {
+    const normalized = method.toUpperCase();
+    switch (normalized) {
+        case "DELETE":
+        case "GET":
+        case "HEAD":
+        case "PATCH":
+        case "POST":
+        case "PUT":
+        case "OPTIONS":
+            return normalized;
+        default:
+            return "GET";
+    }
+}
+export function createHostProjectApiTunnelRequestHandler(options) {
+    return async (request) => {
+        const headers = injectHeaders(request);
+        headers[TRUSTED_RELAY_METADATA_REQUEST_HEADER] = options.trustedMetadataStore.stage(request.metadata);
+        const payload = decodeRequestBody(request.body_base64);
+        const injectOptions = {
+            method: toInjectMethod(request.method),
+            url: request.path,
+            headers,
+        };
+        if (payload !== undefined) {
+            injectOptions.payload = payload;
+        }
+        const response = await options.app.inject(injectOptions);
+        const responsePayload = responseBodyBuffer(response);
+        const tunnelResponse = {
+            request_id: request.request_id,
+            status_code: response.statusCode,
+            headers: responseHeaders(response.headers),
+        };
+        if (responsePayload.length === 0) {
+            return tunnelResponse;
+        }
+        return {
+            ...tunnelResponse,
+            body_base64: responsePayload.toString("base64"),
+        };
+    };
+}
+async function writeFetchBodyToStreamSink(response, sink) {
+    if (response.body === null) {
+        sink.end();
+        return;
+    }
+    const reader = response.body.getReader();
+    try {
+        while (!sink.signal.aborted) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                break;
+            }
+            const value = chunk.value;
+            if (value instanceof Uint8Array) {
+                sink.write(value);
+            }
+            else if (typeof value === "string") {
+                sink.write(value);
+            }
+            else if (value instanceof ArrayBuffer) {
+                sink.write(new Uint8Array(value));
+            }
+            else {
+                throw new Error("Unsupported fetch stream chunk type");
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (!sink.signal.aborted) {
+        sink.end();
+    }
+}
+export function createHostProjectApiTunnelStreamRequestHandler(options) {
+    return async (request, sink) => {
+        const headers = injectHeaders(request);
+        headers[TRUSTED_RELAY_METADATA_REQUEST_HEADER] = options.trustedMetadataStore.stage(request.metadata);
+        const payload = decodeRequestBody(request.body_base64);
+        const init = {
+            method: toInjectMethod(request.method),
+            headers: fetchRequestHeaders(headers),
+            signal: sink.signal,
+        };
+        if (payload !== undefined) {
+            init.body = payload;
+        }
+        const response = await (options.fetch ?? fetch)(new URL(request.path, options.baseUrl), init);
+        sink.start({
+            status_code: response.status,
+            headers: fetchResponseHeaders(response.headers),
+        });
+        await writeFetchBodyToStreamSink(response, sink);
+    };
+}
+//# sourceMappingURL=host-tunnel.js.map

package/dist/server-shell/http/logger.d.ts

@@ -0,0 +1,7 @@
+import { serializeRuntimeRequestLog, serializeRuntimeResponseLog, type RuntimeSerializedErrorLog } from "@tutti/shared/utils";
+import type { FastifyError, FastifyServerOptions } from "fastify";
+export declare const serializeRequestLog: typeof serializeRuntimeRequestLog;
+export declare const serializeResponseLog: typeof serializeRuntimeResponseLog;
+export declare function serializeErrorLog(error: FastifyError): RuntimeSerializedErrorLog;
+export declare function createRedactedLoggerOptions(service: string): Exclude<FastifyServerOptions["logger"], undefined>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/server-shell/http/logger.js

@@ -0,0 +1,19 @@
+import { serializeRuntimeErrorLog, serializeRuntimeRequestLog, serializeRuntimeResponseLog, } from "@tutti/shared/utils";
+export const serializeRequestLog = serializeRuntimeRequestLog;
+export const serializeResponseLog = serializeRuntimeResponseLog;
+export function serializeErrorLog(error) {
+    return serializeRuntimeErrorLog(error);
+}
+export function createRedactedLoggerOptions(service) {
+    return {
+        level: "info",
+        messageKey: "message",
+        base: { service, component: "http" },
+        serializers: {
+            req: serializeRequestLog,
+            res: serializeResponseLog,
+            err: serializeErrorLog,
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/server-shell/http/routes/agent-context-auth.d.ts

@@ -0,0 +1,41 @@
+import type { FastifyRequest } from "fastify";
+import type { ActivityRef, ProjectId } from "@tutti/shared/ids";
+import type { CodexAppServerContextApiScope, CodexAppServerSkillSelectionName } from "../../../providers/openai/app-server/skills.js";
+export declare const DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS: number;
+export type AgentContextTokenRecord = {
+    token: string;
+    project_id: ProjectId;
+    activity_ref?: ActivityRef;
+    selection: CodexAppServerSkillSelectionName;
+    scopes: CodexAppServerContextApiScope[];
+    expires_at: string;
+};
+export declare class AgentContextTokenRegistry {
+    private readonly options;
+    private readonly records;
+    constructor(options?: {
+        now?: () => Date;
+        ttlMs?: number;
+        tokenFactory?: () => string;
+    });
+    issueToken(input: {
+        projectId: ProjectId;
+        activityRef?: ActivityRef;
+        selection: CodexAppServerSkillSelectionName;
+        scopes: CodexAppServerContextApiScope[];
+        ttlMs?: number;
+    }): AgentContextTokenRecord;
+    validate(options: {
+        token: string;
+        projectId: ProjectId;
+        requiredScope: CodexAppServerContextApiScope;
+    }): AgentContextTokenRecord;
+    private now;
+}
+export declare function authorizeAgentContextRequest(request: FastifyRequest, options: {
+    project: {
+        project_id: ProjectId;
+    };
+    tokenRegistry: AgentContextTokenRegistry;
+}, requiredScope: CodexAppServerContextApiScope): void;
+//# sourceMappingURL=agent-context-auth.d.ts.map

package/dist/server-shell/http/routes/agent-context-auth.js

@@ -0,0 +1,73 @@
+import { randomBytes } from "node:crypto";
+export const DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS = 30 * 60 * 1000;
+export class AgentContextTokenRegistry {
+    options;
+    records = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    issueToken(input) {
+        const now = this.now();
+        const ttlMs = input.ttlMs ?? this.options.ttlMs ?? DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS;
+        const token = this.options.tokenFactory?.() ?? `agctx_${randomBytes(32).toString("base64url")}`;
+        const record = {
+            token,
+            project_id: input.projectId,
+            ...(input.activityRef === undefined ? {} : { activity_ref: input.activityRef }),
+            selection: input.selection,
+            scopes: [...new Set(input.scopes)],
+            expires_at: new Date(now.getTime() + ttlMs).toISOString(),
+        };
+        this.records.set(token, record);
+        return record;
+    }
+    validate(options) {
+        const record = this.records.get(options.token);
+        if (record === undefined) {
+            throw new AgentContextAuthError(401, "unauthorized", "Agent context token is invalid");
+        }
+        if (Date.parse(record.expires_at) <= this.now().getTime()) {
+            this.records.delete(options.token);
+            throw new AgentContextAuthError(401, "unauthorized", "Agent context token is expired");
+        }
+        if (record.project_id !== options.projectId) {
+            throw new AgentContextAuthError(403, "forbidden", "Agent context token is not valid here");
+        }
+        if (!record.scopes.includes(options.requiredScope)) {
+            throw new AgentContextAuthError(403, "forbidden", "Agent context scope is not allowed");
+        }
+        return record;
+    }
+    now() {
+        return (this.options.now ?? (() => new Date()))();
+    }
+}
+class AgentContextAuthError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.name = "AgentContextAuthError";
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+function bearerToken(request) {
+    const authorization = request.headers.authorization;
+    if (authorization === undefined) {
+        throw new AgentContextAuthError(401, "unauthorized", "Agent context token is required");
+    }
+    const match = /^Bearer\s+(.+)$/iu.exec(authorization);
+    if (match?.[1] === undefined || match[1].trim() === "") {
+        throw new AgentContextAuthError(401, "unauthorized", "Agent context token is invalid");
+    }
+    return match[1].trim();
+}
+export function authorizeAgentContextRequest(request, options, requiredScope) {
+    options.tokenRegistry.validate({
+        token: bearerToken(request),
+        projectId: options.project.project_id,
+        requiredScope,
+    });
+}
+//# sourceMappingURL=agent-context-auth.js.map

package/dist/server-shell/http/routes/agent-context-errors.d.ts

@@ -0,0 +1,6 @@
+export declare class AgentContextBadRequestError extends Error {
+    readonly statusCode = 400;
+    readonly code = "bad_request";
+    constructor(message: string);
+}
+//# sourceMappingURL=agent-context-errors.d.ts.map

package/dist/server-shell/http/routes/agent-context-errors.js

@@ -0,0 +1,9 @@
+export class AgentContextBadRequestError extends Error {
+    statusCode = 400;
+    code = "bad_request";
+    constructor(message) {
+        super(message);
+        this.name = "AgentContextBadRequestError";
+    }
+}
+//# sourceMappingURL=agent-context-errors.js.map

package/dist/server-shell/http/routes/agent-context-messages-routes.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyInstance } from "fastify";
+import { type AgentContextRouteOptions } from "./agent-context-shared.js";
+export declare function registerAgentContextMessageRoutes(app: FastifyInstance, options: AgentContextRouteOptions): void;
+//# sourceMappingURL=agent-context-messages-routes.d.ts.map

package/dist/server-shell/http/routes/agent-context-messages-routes.js

@@ -0,0 +1,74 @@
+import { readMainChatMessageWindow } from "../../../collaboration-state/index.js";
+import { authorizeAgentContextRequest } from "./agent-context-auth.js";
+import { AgentContextBadRequestError } from "./agent-context-errors.js";
+import { boundedLimit, queryString, truncateText } from "./agent-context-query.js";
+import { AGENT_CONTEXT_BASE_PATH, MESSAGE_BODY_MAX_CHARS, MESSAGE_LIMIT_DEFAULT, MESSAGE_LIMIT_MAX, requireProjectStore, } from "./agent-context-shared.js";
+export function registerAgentContextMessageRoutes(app, options) {
+    app.get(`${AGENT_CONTEXT_BASE_PATH}/messages`, (request) => {
+        authorizeAgentContextRequest(request, options, "messages:read");
+        const query = request.query;
+        const scope = queryString(query.scope) ?? "main_chat";
+        if (scope !== "main_chat") {
+            throw new AgentContextBadRequestError("Message scope is invalid");
+        }
+        const anchorParam = queryString(query.anchor);
+        if (anchorParam !== undefined && anchorParam !== "latest" && anchorParam !== "start") {
+            throw new AgentContextBadRequestError("Message anchor is invalid");
+        }
+        const anchor = anchorParam === "latest" || anchorParam === "start" ? anchorParam : undefined;
+        const cursor = queryString(query.cursor);
+        const limit = boundedLimit(query.limit, {
+            default: MESSAGE_LIMIT_DEFAULT,
+            max: MESSAGE_LIMIT_MAX,
+        });
+        const windowOptions = cursor === undefined
+            ? {
+                limit,
+                ...(anchor === undefined ? {} : { anchor }),
+            }
+            : {
+                limit,
+                before: cursor,
+            };
+        const window = readMainChatMessageWindow(requireProjectStore(options).db, windowOptions);
+        return {
+            scope: "main_chat",
+            items: window.items.map((message) => {
+                const body = truncateText(message.body, MESSAGE_BODY_MAX_CHARS);
+                return {
+                    message_id: message.id,
+                    created_at: message.created_at,
+                    author: {
+                        kind: message.author.kind,
+                        display_name: message.author.display_name ?? message.author.kind,
+                    },
+                    body: body.text,
+                    body_truncated: body.truncated,
+                    ...(message.refs?.reference_file === undefined
+                        ? {}
+                        : {
+                            refs: {
+                                reference_file: {
+                                    path: message.refs.reference_file.path,
+                                    name: message.refs.reference_file.name,
+                                    category: message.refs.reference_file.category,
+                                },
+                            },
+                        }),
+                };
+            }),
+            page: {
+                ...(window.window.older_cursor === undefined
+                    ? {}
+                    : { next_cursor: window.window.older_cursor }),
+                ...(window.window.newer_cursor === undefined
+                    ? {}
+                    : { previous_cursor: window.window.newer_cursor }),
+                has_older: window.window.has_older,
+                has_newer: window.window.has_newer,
+                limit: window.window.limit,
+            },
+        };
+    });
+}
+//# sourceMappingURL=agent-context-messages-routes.js.map

package/dist/server-shell/http/routes/agent-context-project-doc-routes.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyInstance } from "fastify";
+import { type AgentContextRouteOptions } from "./agent-context-shared.js";
+export declare function registerAgentContextProjectDocRoutes(app: FastifyInstance, options: AgentContextRouteOptions): void;
+//# sourceMappingURL=agent-context-project-doc-routes.d.ts.map

package/dist/server-shell/http/routes/agent-context-project-doc-routes.js

@@ -0,0 +1,86 @@
+import { redactText } from "@tutti/shared/utils";
+import { VIEWER_HARD_READ_LIMIT_BYTES, WorkspaceOpsError, readViewerFile, } from "../../../workspace-ops/index.js";
+import { authorizeAgentContextRequest } from "./agent-context-auth.js";
+import { AgentContextBadRequestError } from "./agent-context-errors.js";
+import { boundedLimit, queryString } from "./agent-context-query.js";
+import { containsUnconfirmedPlaceholders, isProjectDocKey, projectDocListItems, projectDocPathForKey, projectDocPurpose, projectDocUnavailableReason, } from "./agent-context-project-docs.js";
+import { AGENT_CONTEXT_BASE_PATH, PROJECT_DOC_FILE_DEFAULT_MAX_BYTES, PROJECT_DOC_FILE_MAX_BYTES, requireWorkspaceRoot, } from "./agent-context-shared.js";
+export function registerAgentContextProjectDocRoutes(app, options) {
+    app.get(`${AGENT_CONTEXT_BASE_PATH}/project-docs`, (request) => {
+        authorizeAgentContextRequest(request, options, "project-docs:list");
+        return {
+            docs: projectDocListItems(options),
+            note: [
+                "Missing or unavailable docs are not runtime failures.",
+                "Use repository inspection and explicit human context when the current turn needs",
+                "to create or reason about missing project docs.",
+            ].join(" "),
+        };
+    });
+    app.get(`${AGENT_CONTEXT_BASE_PATH}/project-docs/file`, (request) => {
+        authorizeAgentContextRequest(request, options, "project-docs:read");
+        const docKey = queryString(request.query.doc_key);
+        if (docKey === undefined || !isProjectDocKey(docKey)) {
+            throw new AgentContextBadRequestError("Project doc key is invalid");
+        }
+        const path = projectDocPathForKey(docKey);
+        const maxBytes = Math.min(boundedLimit(request.query.max_bytes, {
+            default: PROJECT_DOC_FILE_DEFAULT_MAX_BYTES,
+            max: PROJECT_DOC_FILE_MAX_BYTES,
+        }), VIEWER_HARD_READ_LIMIT_BYTES);
+        try {
+            const file = readViewerFile({
+                workspaceRoot: requireWorkspaceRoot(options),
+                path,
+                maxBytes,
+                ...(options.now === undefined ? {} : { now: options.now }),
+            });
+            if (file.content.kind !== "text") {
+                return {
+                    kind: "unavailable",
+                    doc_key: docKey,
+                    path,
+                    status: "unreadable",
+                    reason: file.content.reason,
+                    message: "Project doc exists but is not readable as bounded UTF-8 text.",
+                };
+            }
+            const text = redactText(file.content.text);
+            const containsUnconfirmed = containsUnconfirmedPlaceholders(text);
+            return {
+                kind: "text",
+                doc_key: docKey,
+                path: file.file.path,
+                name: file.file.name,
+                purpose: projectDocPurpose(docKey),
+                text,
+                truncated: file.content.truncated,
+                bytes_read: file.content.bytes_returned,
+                contains_unconfirmed_placeholders: containsUnconfirmed,
+                ...(containsUnconfirmed
+                    ? {
+                        completeness_hint: "This project doc contains unconfirmed placeholders; " +
+                            "treat those sections as unresolved context.",
+                    }
+                    : {}),
+            };
+        }
+        catch (error) {
+            if (error instanceof WorkspaceOpsError) {
+                const reason = projectDocUnavailableReason(error);
+                return {
+                    kind: "unavailable",
+                    doc_key: docKey,
+                    path,
+                    status: reason === "missing" ? "missing" : "unavailable",
+                    reason,
+                    message: reason === "missing"
+                        ? "Project doc has not been created yet."
+                        : "Project doc is not currently readable through the context API.",
+                };
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=agent-context-project-doc-routes.js.map

package/dist/server-shell/http/routes/agent-context-project-docs.d.ts

@@ -0,0 +1,40 @@
+import type { ProjectDocKey } from "@tutti/shared/schemas/api";
+import { WorkspaceOpsError } from "../../../workspace-ops/index.js";
+type AgentContextWorkspaceOptions = {
+    workspaceOps?: {
+        workspaceRoot: string;
+    };
+    now?: () => Date;
+};
+export declare function isProjectDocKey(value: string): value is ProjectDocKey;
+export declare function projectDocPurpose(docKey: ProjectDocKey): string;
+export declare function projectDocUnavailableReason(error: WorkspaceOpsError): string;
+export declare function containsUnconfirmedPlaceholders(text: string): boolean;
+export declare function projectDocPathForKey(docKey: ProjectDocKey): string;
+export declare function projectDocListItems(options: AgentContextWorkspaceOptions): ({
+    doc_key: "product" | "tech" | "structure" | "architecture_principles";
+    path: string;
+    purpose: string;
+    status: "unreadable";
+    reason: string;
+    size_bytes?: never;
+    message?: never;
+} | {
+    doc_key: "product" | "tech" | "structure" | "architecture_principles";
+    path: string;
+    purpose: string;
+    status: "available";
+    size_bytes: number;
+    reason?: never;
+    message?: never;
+} | {
+    doc_key: "product" | "tech" | "structure" | "architecture_principles";
+    path: string;
+    purpose: string;
+    status: "unavailable";
+    reason: string;
+    message: string;
+    size_bytes?: never;
+})[];
+export {};
+//# sourceMappingURL=agent-context-project-docs.d.ts.map

package/dist/server-shell/http/routes/agent-context-project-docs.js

@@ -0,0 +1,98 @@
+import { PROJECT_DOCS } from "../../../project-docs/context.js";
+import { WorkspaceOpsError, readViewerFile, } from "../../../workspace-ops/index.js";
+import { AgentContextBadRequestError } from "./agent-context-errors.js";
+function requireWorkspaceRoot(options) {
+    if (options.workspaceOps === undefined) {
+        throw new AgentContextBadRequestError("Workspace viewer is unavailable");
+    }
+    return options.workspaceOps.workspaceRoot;
+}
+export function isProjectDocKey(value) {
+    return PROJECT_DOCS.some((doc) => doc.doc_key === value);
+}
+export function projectDocPurpose(docKey) {
+    switch (docKey) {
+        case "product":
+            return "Purpose, target users, key features, and business objectives.";
+        case "tech":
+            return "Frameworks, libraries, development tools, and technical constraints.";
+        case "structure":
+            return "File organization, naming conventions, import patterns, and architectural decisions.";
+        case "architecture_principles":
+            return "Scope, core principles, boundary rules, quality gates, human escalation, and documentation duties.";
+    }
+}
+export function projectDocUnavailableReason(error) {
+    if (error.code === "not_found") {
+        return "missing";
+    }
+    if (error.code === "repo_snapshot_unavailable") {
+        return "repo_snapshot_unavailable";
+    }
+    if (error.code === "forbidden") {
+        return "restricted_path";
+    }
+    if (error.code === "validation_failed") {
+        return "restricted_path";
+    }
+    throw error;
+}
+export function containsUnconfirmedPlaceholders(text) {
+    return /\b(?:to be confirmed|tbd|todo)\b/iu.test(text);
+}
+export function projectDocPathForKey(docKey) {
+    const doc = PROJECT_DOCS.find((candidate) => candidate.doc_key === docKey);
+    if (doc === undefined) {
+        throw new AgentContextBadRequestError("Project doc key is invalid");
+    }
+    return doc.path;
+}
+export function projectDocListItems(options) {
+    return PROJECT_DOCS.map((doc) => projectDocListItem(options, doc));
+}
+function projectDocListItem(options, doc) {
+    try {
+        const file = readViewerFile({
+            workspaceRoot: requireWorkspaceRoot(options),
+            path: doc.path,
+            maxBytes: 1,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        const reason = unavailableReasonForContent(file.content);
+        if (reason !== undefined) {
+            return {
+                doc_key: doc.doc_key,
+                path: doc.path,
+                purpose: projectDocPurpose(doc.doc_key),
+                status: "unreadable",
+                reason,
+            };
+        }
+        return {
+            doc_key: doc.doc_key,
+            path: doc.path,
+            purpose: projectDocPurpose(doc.doc_key),
+            status: "available",
+            size_bytes: file.file.size_bytes,
+        };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceOpsError) {
+            return {
+                doc_key: doc.doc_key,
+                path: doc.path,
+                purpose: projectDocPurpose(doc.doc_key),
+                status: "unavailable",
+                reason: projectDocUnavailableReason(error),
+                message: error.code === "not_found"
+                    ? "Project doc has not been created yet."
+                    : "Project doc is not currently readable through the context API.",
+            };
+        }
+        throw error;
+    }
+}
+function unavailableReasonForContent(content) {
+    return content.kind === "text" ? undefined : content.reason;
+}
+//# sourceMappingURL=agent-context-project-docs.js.map

package/dist/server-shell/http/routes/agent-context-query.d.ts

@@ -0,0 +1,31 @@
+type OffsetCursor = {
+    endpoint: "worklist" | "references" | "skills";
+    offset: number;
+};
+export declare function queryString(value: unknown): string | undefined;
+export declare function boundedLimit(value: unknown, defaults: {
+    default: number;
+    max: number;
+}): number;
+export declare function truncateText(value: string | undefined, maxChars: number): {
+    text: string;
+    truncated: boolean;
+};
+export declare function truncateArray(values: string[], maxItems: number, maxItemChars: number): {
+    items: string[];
+    truncated: boolean;
+};
+export declare function pageByOffset<T>(items: T[], options: {
+    endpoint: OffsetCursor["endpoint"];
+    cursor?: string;
+    limit: number;
+}): {
+    items: T[];
+    page: {
+        limit: number;
+        has_more: boolean;
+        next_cursor?: string;
+    };
+};
+export {};
+//# sourceMappingURL=agent-context-query.d.ts.map