@agwab/pi-workflow 0.1.1 → 0.1.2

package/dist/workflow-web-source.d.ts

@@ -0,0 +1,171 @@
+export declare const WORKFLOW_WEB_SOURCE_CACHE_SCHEMA: "workflow-web-source-cache-v1";
+export declare const WORKFLOW_WEB_SOURCE_INDEX_SCHEMA: "workflow-web-source-index-v1";
+export declare const WORKFLOW_WEB_SOURCE_INDEX_EVENT_SCHEMA: "workflow-web-source-index-event-v1";
+export declare const WORKFLOW_WEB_SOURCE_EVENT_SCHEMA: "workflow-web-source-event-v1";
+export declare const WORKFLOW_WEB_SOURCE_TOOLS: readonly ["workflow_web_search", "workflow_web_fetch_source", "workflow_web_source_read"];
+export type WorkflowWebSourceTool = (typeof WORKFLOW_WEB_SOURCE_TOOLS)[number];
+export interface WorkflowWebSourcePolicy {
+    previewChars: number;
+    duplicatePreviewChars: number;
+    sourceReadMaxChars: number;
+    searchSnippetChars: number;
+    perTaskVisibleCharBudget: number;
+}
+export interface WorkflowWebSecurityPolicy {
+    allowPrivateHosts: boolean;
+    cacheRawProviderPayloads: boolean;
+}
+export interface WorkflowWebSourceCacheConfig {
+    runId: string;
+    taskId: string;
+    cacheDir: string;
+}
+export interface WorkflowWebSource {
+    schema: typeof WORKFLOW_WEB_SOURCE_CACHE_SCHEMA;
+    sourceRef: string;
+    createdAt: string;
+    runId: string;
+    taskId: string;
+    url: string;
+    redactedUrl: string;
+    urlKey?: string;
+    domain: string;
+    title?: string;
+    provider?: string;
+    contentHash: string;
+    text: string;
+    textChars: number;
+    extractionLossy?: boolean;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+export interface WorkflowWebSourceIndexEntry {
+    sourceRef: string;
+    createdAt: string;
+    url: string;
+    redactedUrl: string;
+    urlKey?: string;
+    domain: string;
+    title?: string;
+    contentHash: string;
+    textChars: number;
+    provider?: string;
+}
+export interface WorkflowWebSourceIndex {
+    schema: typeof WORKFLOW_WEB_SOURCE_INDEX_SCHEMA;
+    updatedAt: string;
+    runId: string;
+    sources: WorkflowWebSourceIndexEntry[];
+}
+export interface WorkflowWebVisibleBudget {
+    limit: number;
+    used: number;
+}
+export interface WorkflowWebSourceReadRequest {
+    query?: string;
+    claim?: string;
+    terms?: string[];
+    maxChars?: number;
+}
+export interface WorkflowWebSourceReadResult {
+    status: "matched" | "not_found";
+    matchType?: "exact" | "normalized" | "terms";
+    quote?: string;
+    startOffset?: number;
+    endOffset?: number;
+    visibleChars: number;
+    matchedTerms?: string[];
+    missingTerms?: string[];
+    coverageRatio?: number;
+    candidateOnly?: boolean;
+}
+export interface WorkflowWebSourceCard {
+    sourceRef: string;
+    url: string;
+    domain: string;
+    title?: string;
+    preview: string;
+    textChars: number;
+    fullContentCached: boolean;
+    duplicate: boolean;
+    budget: {
+        limit: number;
+        used: number;
+        remaining: number;
+        truncated: boolean;
+    };
+    next: string;
+}
+export interface WorkflowWebSearchCandidate {
+    url?: string;
+    title?: string;
+    snippet: string;
+    domain?: string;
+}
+export declare const DEFAULT_WORKFLOW_WEB_SOURCE_POLICY: WorkflowWebSourcePolicy;
+export declare const DEFAULT_WORKFLOW_WEB_SECURITY_POLICY: WorkflowWebSecurityPolicy;
+export declare function normalizeWorkflowWebSourcePolicy(policy: Partial<WorkflowWebSourcePolicy> | undefined): WorkflowWebSourcePolicy;
+export declare function normalizeWorkflowWebSecurityPolicy(policy: Partial<WorkflowWebSecurityPolicy> | undefined): WorkflowWebSecurityPolicy;
+export declare function isWorkflowWebSourceTool(tool: string): tool is WorkflowWebSourceTool;
+export declare function createWorkflowWebVisibleBudget(limit: number): WorkflowWebVisibleBudget;
+export declare function consumeWorkflowWebVisibleBudget(budget: WorkflowWebVisibleBudget, text: string, maxChars: number): {
+    text: string;
+    truncated: boolean;
+    remaining: number;
+    used: number;
+};
+export declare function validateWorkflowWebUrl(url: string, security?: WorkflowWebSecurityPolicy): {
+    ok: true;
+    normalizedUrl: string;
+    domain: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function sanitizeUrlForModel(url: string): string;
+export declare function sourceRefFor(url: string, text: string): string;
+export declare function sourceUrlCacheKey(url: string): string;
+export declare function createWorkflowWebSource(options: {
+    config: WorkflowWebSourceCacheConfig;
+    url: string;
+    text: string;
+    title?: string;
+    provider?: string;
+    extractionLossy?: boolean;
+    metadata?: WorkflowWebSource["metadata"];
+}): WorkflowWebSource;
+export declare function writeWorkflowWebSource(config: WorkflowWebSourceCacheConfig, source: WorkflowWebSource): Promise<void>;
+export declare function readWorkflowWebSource(config: WorkflowWebSourceCacheConfig, sourceRef: string): Promise<WorkflowWebSource | undefined>;
+export declare function readWorkflowWebSourceIndex(config: WorkflowWebSourceCacheConfig): Promise<WorkflowWebSourceIndex>;
+export declare function findWorkflowWebSourceByUrl(config: WorkflowWebSourceCacheConfig, url: string): Promise<WorkflowWebSource | undefined>;
+export declare function recordWorkflowWebSourceEvent(config: WorkflowWebSourceCacheConfig, event: string, data?: Record<string, unknown>): Promise<void>;
+export declare function buildWorkflowWebSourceCard(options: {
+    source: WorkflowWebSource;
+    policy: WorkflowWebSourcePolicy;
+    budget: WorkflowWebVisibleBudget;
+    duplicate?: boolean;
+}): WorkflowWebSourceCard;
+export declare function readWorkflowWebSourceSnippet(options: {
+    source: WorkflowWebSource;
+    query?: string;
+    claim?: string;
+    terms?: string[];
+    maxChars: number;
+    budget: WorkflowWebVisibleBudget;
+}): WorkflowWebSourceReadResult;
+export declare function readWorkflowWebSourceSnippets(options: {
+    source: WorkflowWebSource;
+    requests: WorkflowWebSourceReadRequest[];
+    maxChars: number;
+    budget: WorkflowWebVisibleBudget;
+}): WorkflowWebSourceReadResult[];
+export declare function extractTextFromToolResult(result: unknown): string;
+export declare function extractTitleFromToolResult(result: unknown): string | undefined;
+export declare function extractSearchCandidates(result: unknown, policy?: WorkflowWebSourcePolicy): WorkflowWebSearchCandidate[];
+export declare function toolResultFromJson(value: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+};
+export declare function errorToolResult(code: string, message: string, extra?: Record<string, unknown>): ReturnType<typeof toolResultFromJson>;