@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/asse
 export { createReportSessionSpawn } from "./app/spawn-report-session.js";
 export type { ReportSessionSpawn, ReportSessionSpawnDeps, ReportSessionPaging, SpawnRefusal, ReportBrief, ReportSessionDelta, NewestReportChild, } from "./app/spawn-report-session.js";
 export { launchPlanRun } from "./tools/execute-analysis.js";
-export type { LaunchPlanRunDeps, LaunchPlanRunRefusal, PlanLaunch } from "./tools/execute-analysis.js";
+export type { LaunchPlanRunDeps, LaunchPlanRunInput, LaunchPlanRunRefusal, PlanLaunch } from "./tools/execute-analysis.js";
 export { approvePlan } from "./app/approve-plan.js";
 export type { ApprovePlanDeps, ApprovePlanInput, ApprovePlanRefusal, PlanApproval } from "./app/approve-plan.js";
 export type { EnsureSessionStateResult } from "./app/report-session-runtime.js";
@@ -27,7 +27,7 @@ export { createConversationAgent } from "./agents/conversation-agent.js";
 export type { ConversationAgentDeps } from "./agents/conversation-agent.js";
 export type { BioToolKeys } from "./tools/bio/keys.js";
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
-export type { RunAuthorizer, AuthorizeRunInput, RunAuthorization, RevokeByJtiRef } from "./execution/run-authorizer.js";
+export type { RunAuthorizer, AuthorizeRunInput, RevokeByMandateRef } from "./execution/run-authorizer.js";
 export type { GateFailure, NoticeFailure } from "./lib/hooks.js";
 export type { RequestHeaders, ResolveRequestHeaders } from "./providers/request-headers.js";
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
@@ -52,23 +52,23 @@ export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 export type { RunCanceler, RunCancelerDeps, CancelRunResult } from "./execution/run-canceler.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
+export type { KnowledgeClient, KnowledgeSituation, HttpKnowledgeClientConfig } from "./tools/knowledge/index.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 export { createCitationResolver } from "./citations/resolve.js";
 export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
+export type { WebSearchEngine } from "./tools/research/web-search.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 export type { CitationKind, CitationInput, CitationSource, CitationSourceStatus, CitationResolver, CitationResolveOptions, CitationResolutionResult, CitationVerdict, CitationCoverage, ComparisonStatus, CitationField, UnsupportedWorkKind, CitationIdentifiers, NormalizedCitationMetadata, NormalizedCitation, CitationSourceOutcome, CitationRecord, IdentifierEvidence, CitationFieldComparison, CitationConflict, CitationCandidateCluster, CitationSourceClient, CitationSourceRequest, CitationSourceOperation, CitationSourcePlanItem, RegistrationAgencyEvidence, } from "./citations/types.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
-export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
-export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
-export type { Ask, AskRequest, AskReply, AskApproval } from "./tools/approval/contract.js";
-export { runAgent, finalText } from "./loop/run-agent.js";
-export type { RunAgentOptions, RunAgentResult, AgentFinish, AgentRound } from "./loop/run-agent.js";
-export type { CompactionPolicy, CompactionRules } from "./loop/compaction.js";
-export type { ToolMask } from "./loop/tool-mask.js";
-export type { AgentDefinition, RunStep, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
+export type { AskGateway, AskGatewayDeps, AskScope, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
+export type { AskRequest, AskReply } from "./tools/approval/contract.js";
+export type { AgentFinish, AgentRound } from "./loop/run-loop.js";
+export type { CompactionRules } from "./loop/compaction.js";
+export type { AgentDefinition, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
 export type { KeptToolOutput, ToolOutputStore } from "./loop/tool-output.js";
-export { passthroughStep } from "./loop/run-step.js";
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
 export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, HookSessionView, ResolvableSession, } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
@@ -76,36 +76,37 @@ export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./prov
 export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps, ProviderHostPolicy } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
-export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
+export type { BoundModel, ChatProvider, EmbeddingProvider, ChatStreamEvent, ChatUsage, ModelBinding, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
 export { CONVERSATION_PROMPT_CACHE, DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
 export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
 export type { SuspendOn } from "./providers/errors.js";
-export { suspensionOfFailure } from "./workflows/suspension.js";
-export type { Suspension } from "./workflows/suspension.js";
-export { createStreamingChat } from "./providers/streaming-chat.js";
-export { openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
-export type { ChatTurnOutcome, ChatTurnRan, ChatTurnRefusal, ChatTurnResult, ChatTurnSession, OpenChatTurn, OpenChatTurnParams, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult, RunChatTurnDeps, RunChatTurnParams, RunOpenChatTurnParams, } from "./app/chat-turn.js";
+export { DEFAULT_PAUSE_RETRY_DELAYS_MS } from "./workflows/pause.js";
+export type { PausedWorkflow, Work, WorkHold, WorkResume, WorkStop, WorkSurface } from "./app/work.js";
+export { DATA_PROFILE_STOPPED } from "./tasks/data-profile.js";
+export { prepareChatTurn } from "./app/chat-turn.js";
+export type { ChatTurnRefusal, ChatTurnSession, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
+export type { ChatTurnEnd, ChatTurns, ChatTurnStart, OpenChatTurnRequest } from "./app/chat-turn-workflow.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ListRecentThreadsInput, ThreadPage, } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, LoadPageOptions, TurnPage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
 export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions } from "./memory/conversation-display-recorder.js";
 export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMessage, StoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
-export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
-export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
+export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, MessageStartEvent, } from "./contracts/chat-events.js";
+export { toChatFrame, applyChatFrame, checkChatPart, isKnownPartFrame } from "./contracts/chat-frame.js";
 export { createSubAgentActivityTracker, SUBAGENT_ACTIVITY_MAX_ENTRIES } from "./contracts/subagent-activity.js";
 export type { SubAgentActivityTracker } from "./contracts/subagent-activity.js";
 export type { TextPart, ToolCallPart, MessagePart, ChatMessage } from "./contracts/message.js";
 export type { TurnTerminal, ApplyFrameResult, ChatPartCheck } from "./contracts/chat-frame.js";
 export type { TokenUsageRollup } from "./contracts/usage.js";
-export type { ChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, PlanApprovalPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, PlanGraphStep, StepStatus, StepActivityPart, ActivityEntryPart, SubAgentActivityEntry, SubAgentActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, FindingReference, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, CompactionPart, AskPart, ChildSessionStartedPart, ReportRenderedPart, } from "./contracts/chat-parts.js";
+export type { ChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, PlanApprovalPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, PlanGraphStep, StepStatus, StepActivityPart, ActivityEntryPart, SubAgentActivityEntry, SubAgentActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, FindingReference, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, CompactionPart, PauseCause, WorkKind, PausePart, ModelRetryPart, AskPart, ChildSessionStartedPart, ReportRenderedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 export type { ChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";
@@ -140,8 +141,8 @@ export type { DataProfileAxis, DataProfileChecked, DataProfileCompanionCompleten
 export type { DataProfileStatus } from "./state/data-profile.js";
 export { queryLatestRunsByAnalyses, queryDataProfileStatusByAnalyses, queryRunProgressByRuns, queryRunsEndedSince } from "./state/analyses-metrics.js";
 export type { DataProfileSummary, EndedRunSummary, LatestRunSummary, RunProgressSummary } from "./state/analyses-metrics.js";
-export { queryArtifactPage, countArtifactsByRuns } from "./state/artifacts.js";
-export type { ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount } from "./state/artifacts.js";
+export { queryArtifactPage, queryArtifactOrigins, countArtifactsByRuns } from "./state/artifacts.js";
+export type { ArtifactExtensionCount, ArtifactOrigin, ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount, } from "./state/artifacts.js";
 export { readRunSynthesis } from "./execution/run-synthesis.js";
 export type { ReadSynthesisInput } from "./execution/run-synthesis.js";
 export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBES, DIMENSION_PROBE_IDS, GROUP_CATEGORIES, GROUP_CATEGORY_IDS, GROUP_ROLES, GROUP_ROLE_IDS, PROBE_OUTCOME_IDS, dimensionCategoryEntry, dimensionScope, groupCategoryEntry, } from "./contracts/profile-vocabulary.js";
@@ -191,7 +192,7 @@ export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
 export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
 export type { UpsertPlanInput, PlanRecord } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export type { InsertRunInput, RunReservation } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus, TerminalRunStatus } from "./state/schema.js";

package/dist/index.js

@@ -70,6 +70,10 @@ export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// The knowledge plane: an embedder binds a client at its composition root
+// (or none), and it can hand `knowledge_recommend` to the conversation agent
+// through `hostTools`.
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
 // Tool-call-detail authoring aids for an embedder that contributes a host tool.
 // A `describeCall` hook that pre-empts truncation — a count in place of a
 // mid-value cut that would name a file that does not exist — must gate on the
@@ -81,20 +85,19 @@ export { defineTool, isToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 // Host-agnostic citation verification service and its public contracts.
 export { createCitationResolver } from "./citations/resolve.js";
+// The web-search engine type and the SearXNG realization. An embedder cannot
+// build its composition root without these two names: it constructs the engine
+// and types the `webSearch` field of `ConversationAgentDeps` (the front-door
+// rule of the harness-embedder-exports spec). The tools stay off the barrel —
+// the conversation agent constructs them itself.
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
-// Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
-// over the injected `Pool` and carries the outward `answer`/`pending` API plus
-// the boot-time `sweepExpired`; `UnavailableAsk` is the shipped deny-by-default
-// realization for an unwired or non-interactive host. The `AskRequest`/`AskReply`
-// contract and the `AskRejectedError` denial throw come from the seam contract.
+// Tool approval. The approval hook of a tool gives an `AskRequest`, and a turn
+// workflow raises it in the ask ledger of `createAskGateway`. A host lists the
+// pending asks with `pending`, answers one with the `answer` of
+// `CoreRuntime.chatTurns`, and expires the orphans of a dead process with the
+// boot-time `sweepExpired`.
 export { createAskGateway } from "./tools/approval/gateway.js";
-export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
-// Agent loop.
-export { runAgent, finalText } from "./loop/run-agent.js";
-// `passthroughStep` is the in-process `RunStep`: the host request/chat path runs
-// the loop with no durability wrapper (workflow contexts use the durable step).
-// An embedder driving `runAgent` outside a workflow passes it as `runStep`.
-export { passthroughStep } from "./loop/run-step.js";
 // Session value objects + helpers.
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
@@ -108,34 +111,30 @@ export { createEmbeddingProvider } from "./providers/embedding.js";
 // to the request itself, or a proxy miscounts. The root chat loop gets
 // `CONVERSATION_PROMPT_CACHE` (1h), because a person can reply minutes later.
 export { CONVERSATION_PROMPT_CACHE, DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
-// Effort resolves in order: `ChatRequest.reasoning`, the provider config's
+// Effort resolves in order: the effort of the run, the provider config's
 // `reasoning`, then `DEFAULT_REASONING`, downgraded to what the model accepts.
 // A model with no reasoning support takes `"provider-default"`.
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
-// Provider error channel. `ProviderError` is the value `chat`/`embed` fail
-// with; `toProviderError` is its sole constructor. Exposed so an embedder
-// realizing its own `ChatProvider`/`EmbeddingProvider` fails with the exact
-// same shape the harness's own realizations do, rather than re-deriving it.
-// `isProviderError` is the structural guard an embedder driving `chatStream`
-// directly needs: `chatStream` throws a `ProviderError` value (a plain object,
-// not an `Error`), so a `catch` recognizes it by shape, not `instanceof`.
+// Provider error channel. `ProviderError` is the value a model call and `embed`
+// fail with; `toProviderError` is its sole constructor. Exposed so an embedder
+// realizing its own `EmbeddingProvider` fails with the exact same shape the
+// harness's own realizations do, rather than re-deriving it. `isProviderError`
+// is the structural guard of that plain-object value.
 export { toProviderError, isProviderError } from "./providers/errors.js";
 // The suspend map of a provider: an HTTP status to the suspend reason of the
 // host. A map from the host replaces `DEFAULT_SUSPEND_ON`, which holds `402`.
 export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
-// The suspension of work. A host reads the suspend reason of a failed chat turn
-// with `suspensionOfFailure`, by the kind of the error, never by its text.
-export { suspensionOfFailure } from "./workflows/suspension.js";
-// `createStreamingChat` wraps a `ChatProvider` as a streaming `AgentChat` (the
-// type `runAgent`'s `provider` option takes): its `chat` drives the provider's
-// `chatStream` and forwards each text delta to `onText`, so a same-process host
-// gets live token streaming out of the otherwise non-streaming loop.
-export { createStreamingChat } from "./providers/streaming-chat.js";
-// Conversation turn + thread memory. A host runs a chat turn with `runChatTurn`
-// and gives only its transport values: the harness stores the opening, each round,
-// and the outcome. `appendTurn` stays for a record of a host. `createThreadStore`
-// owns thread metadata (create/list/title).
-export { openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
+// The durable work of an analysis. A host lists the active work, stops it, and
+// resumes or holds paused work with `CoreRuntime.work`, and it reads the
+// `data-pause` part of each waiting workflow in the stream of the work.
+export { DEFAULT_PAUSE_RETRY_DELAYS_MS } from "./workflows/pause.js";
+export { DATA_PROFILE_STOPPED } from "./tasks/data-profile.js";
+// Conversation turn + thread memory. A host opens a chat turn with the `open`
+// of `CoreRuntime.chatTurns`, which starts the workflow of the turn, and reads
+// its frames with `read`, live or again after a lost connection. The harness
+// stores the opening, each round, and the outcome. `appendTurn` stays for a
+// record of a host. `createThreadStore` owns thread metadata (create/list/title).
+export { prepareChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 // The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's
@@ -160,7 +159,7 @@ export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/co
 // one thing a read can now meet and not understand — a part whose key this vocabulary has retired —
 // by dropping that part, so one stale row cannot fail a whole thread.
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
-export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
+export { toChatFrame, applyChatFrame, checkChatPart, isKnownPartFrame } from "./contracts/chat-frame.js";
 export { createSubAgentActivityTracker, SUBAGENT_ACTIVITY_MAX_ENTRIES } from "./contracts/subagent-activity.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 // The source grammar of a `structure` presentation card — a host re-runs the same parse over a
@@ -223,8 +222,8 @@ export { upsertAnalysis } from "./state/analyses.js";
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
 // The grouped reads that summarize a page of analyses: one statement for the whole list.
 export { queryLatestRunsByAnalyses, queryDataProfileStatusByAnalyses, queryRunProgressByRuns, queryRunsEndedSince } from "./state/analyses-metrics.js";
-// The artifact ledger reads of one analysis: one page with an exact total, and the step-output count of each run of a list in one statement.
-export { queryArtifactPage, countArtifactsByRuns } from "./state/artifacts.js";
+// The artifact ledger reads of one analysis: one page with an exact total, the origin of each path of a list, and the step-output count of each run of a list, each list in one statement.
+export { queryArtifactPage, queryArtifactOrigins, countArtifactsByRuns } from "./state/artifacts.js";
 // The validated synthesis record of a run as the flat `data-run-synthesis` part of the run stream, or null.
 export { readRunSynthesis } from "./execution/run-synthesis.js";
 // The controlled vocabulary the profiler draws from, as data. A consumer rendering a
@@ -296,7 +295,7 @@ export { validatePlan } from "./schemas/validate-plan.js";
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
 export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 // Host-neutral reference-data catalog and shared installation receipts. Each
 // artifact names the third-party upstream it is fetched from; embedders own all

package/dist/input-sanitization.js

@@ -10,7 +10,7 @@
  * C0/C1 control characters and DEL, excluding `\t` (U+0009) and `\n`
  * (U+000A) which are legitimate whitespace in user prose.
  */
-// eslint-disable-next-line no-control-regex -- matching control characters is the intent: this pattern strips invisible C0/C1 bytes and DEL from untrusted user input (see `normalizeUnicode` below).
+// oxlint-disable-next-line no-control-regex, eslint-js/no-restricted-syntax -- matching control characters is the intent: this pattern strips invisible C0/C1 bytes and DEL from untrusted user input (see `normalizeUnicode` below).
 const CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 /**
  * NFC-normalize and strip control characters.
@@ -31,7 +31,7 @@ export function normalizeUnicode(text) {
  * arrives through no fault of the model: tool results carry raw command output
  * and file bytes, which is why they are otherwise left unsanitized.
  */
-// eslint-disable-next-line no-control-regex -- matching NUL is the intent; see above.
+// oxlint-disable-next-line no-control-regex, eslint-js/no-restricted-syntax -- matching NUL is the intent; see above.
 const NUL = /\u0000/g;
 /**
  * Strip every NUL from `text`. Applied where a tool result is built — so the
@@ -58,17 +58,24 @@ export function stripNulCharacters(text) {
  * Anthropic label wins; `sk-(?!ant-)` additionally excludes it by lookahead.
  */
 const SECRET_PATTERNS = [
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the AWS access-key format with its fixed AKIA prefix and 16-character id body.
     { name: "AWS Access Key", pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the Anthropic key format with its sk-ant- prefix and base64url body.
     { name: "Anthropic API Key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the generic OpenAI sk- format; the (?!ant-) lookahead keeps the Anthropic label ahead of it.
     { name: "OpenAI API Key", pattern: /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}\b/g },
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the GitHub token format with its gh*_ prefix and 36-character body.
     { name: "GitHub Token", pattern: /\bgh[psoru]_[A-Za-z0-9_]{36,}\b/g },
     {
         name: "JWT Token",
+        // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the three dot-separated base64url JWT segments after the eyJ signature prefix.
         pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
     },
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the Bearer scheme with its token characters and padding, the header form of a leaked credential.
     { name: "Bearer Token", pattern: /\bBearer\s+[A-Za-z0-9_\-.~+/]+=*/gi },
     {
         name: "Connection String",
+        // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the DB connection schemes with their :// and unquoted authority, the connection-string form of a leaked credential.
         pattern: /\b(?:postgres|postgresql|mysql|mongodb|redis|amqp|mssql):\/\/[^\s"'`]+/gi,
     },
 ];

package/dist/input-scan/clustering.d.ts

@@ -14,24 +14,24 @@
  * {@link ContentSimilarity}.
  */
 import type { MemberFile } from "./set-types.js";
-export interface DirectoryNode {
+export type DirectoryNode = {
     readonly name: string;
     readonly children: Map<string, DirectoryNode>;
     readonly files: MemberFile[];
     readonly fineSignature: Set<string>;
     readonly coarseSignature: Set<string>;
     readonly childNames: Set<string>;
-}
+};
 /** One concrete directory, carrying the values of the template positions above it. */
-export interface DirectoryEntry {
+export type DirectoryEntry = {
     readonly node: DirectoryNode;
     readonly varValues: readonly string[];
-}
+};
 /** What a content-schema comparison would be given to judge two candidate clusters by. */
-export interface ClusterEvidence {
+export type ClusterEvidence = {
     readonly names: readonly string[];
     readonly files: readonly MemberFile[];
-}
+};
 /**
  * Similarity from file contents — header fields, delimiters, column names.
  *

package/dist/input-scan/clustering.js

@@ -15,16 +15,18 @@
  */
 import { DATE_SYMBOL, DIGIT_SYMBOL, ID_SYMBOL, maskSegment, skeletonOf, tokenizeName } from "./tokens.js";
 import { COARSE_SIMILARITY, CONTAINMENT_SIMILARITY, FINE_SIMILARITY, MAX_SIGNATURE_KEYS } from "./tuning.js";
+import { firstSegmentOf } from "../lib/text.js";
 function newNode(name) {
     return { name, children: new Map(), files: [], fineSignature: new Set(), coarseSignature: new Set(), childNames: new Set() };
 }
+import { presentAt } from "../lib/present.js";
 export function buildTree(files) {
     const root = newNode("");
     for (const file of files) {
         const segments = file.path.split("/");
         let node = root;
         for (let i = 0; i < segments.length - 1; i++) {
-            const name = segments[i];
+            const name = presentAt(segments, i, "path segments");
             let child = node.children.get(name);
             if (!child) {
                 child = newNode(name);
@@ -95,8 +97,10 @@ function hasMask(skeleton) {
 function skeletonKin(a, b) {
     if (a === b && hasMask(a))
         return true;
-    const head = a.split(/[_\-.]/)[0];
-    return head === b.split(/[_\-.]/)[0] && hasMask(head);
+    const head = firstSegmentOf(a, "_-.");
+    if (head === undefined)
+        return false;
+    return head === firstSegmentOf(b, "_-.") && hasMask(head);
 }
 function filesUnder(node, out = []) {
     out.push(...node.files);
@@ -193,9 +197,11 @@ export function clusterChildren(entries, contentSimilarity) {
         let merged = false;
         for (let i = 0; i < clusters.length && !merged; i++) {
             for (let j = i + 1; j < clusters.length; j++) {
-                if (!agrees(clusters[i], clusters[j], contentSimilarity))
+                const left = presentAt(clusters, i, "directory clusters");
+                const right = presentAt(clusters, j, "directory clusters");
+                if (!agrees(left, right, contentSimilarity))
                     continue;
-                absorb(clusters[i], clusters[j]);
+                absorb(left, right);
                 clusters.splice(j, 1);
                 merged = true;
                 break;

package/dist/input-scan/companions.js

@@ -8,6 +8,7 @@
  * into a second set that mirrors the first.
  */
 import { basenameOf } from "./tokens.js";
+import { presentGet } from "../lib/present.js";
 import { EXPECTED_COMPANION_SHARE, MAX_INCOMPLETE_SAMPLE } from "./tuning.js";
 /** Suffixes that name a helper file. The list is a floor; growth is additive. */
 const COMPANION_SUFFIXES = [".bai", ".crai", ".tbi", ".csi", ".idx", ".fai", ".gzi", ".dict", ".md5", ".sha1", ".sha256"];
@@ -80,7 +81,7 @@ export function attachCompanions(files) {
         if (root === undefined)
             continue;
         const bucket = attached.get(root);
-        const companion = { path: file.path, suffix: suffixes.get(file.path), size: file.size };
+        const companion = { path: file.path, suffix: presentGet(suffixes, file.path, "companion suffixes"), size: file.size };
         if (bucket)
             bucket.push(companion);
         else
@@ -96,7 +97,7 @@ export function attachCompanions(files) {
             name: basenameOf(file.path),
             size: file.size,
             format: file.format,
-            ...(file.wrapper ? { wrapper: file.wrapper } : {}),
+            wrapper: file.wrapper,
             companions,
         });
     }

package/dist/input-scan/detect-sets.d.ts

@@ -16,9 +16,9 @@
 import type { ContentSimilarity } from "./clustering.js";
 import type { DetectedSets } from "./set-types.js";
 import type { ScannedFile } from "./types.js";
-export interface DetectSetsOptions {
+export type DetectSetsOptions = {
     /** Read-based agreement between candidate clusters, when the caller has header readouts. */
     readonly contentSimilarity?: ContentSimilarity;
-}
+};
 /** Observe the detected sets of a scanned tree. Pure — no I/O, no container, no model. */
 export declare function detectSets(files: readonly ScannedFile[], options?: DetectSetsOptions): DetectedSets;

package/dist/input-scan/detect-sets.js

@@ -19,6 +19,7 @@ import { applyMarkers } from "./markers.js";
 import { quarantine } from "./quarantine.js";
 import { selectReadouts } from "./readout-budget.js";
 import { catchAll, describeGroup, describeSlot, mineContext, slotToken } from "./templates.js";
+import { presentAt } from "../lib/present.js";
 import { IDENTITY_CROSS_CHECK_RATIO, MAX_EXAMPLE_PATHS, MAX_LEFTOVER_SAMPLE, MAX_SETS_PER_CONTEXT, MIN_IDENTITY_TOKEN_LENGTH } from "./tuning.js";
 function fileCountOf(members) {
     return members.reduce((total, member) => total + 1 + member.companions.length, 0);
@@ -41,7 +42,7 @@ function wrapperCensus(members) {
     return [...counts.entries()].map(([wrapper, count]) => ({ wrapper, count })).sort((a, b) => b.count - a.count || a.wrapper.localeCompare(b.wrapper, "en"));
 }
 function renderTemplate(segments, slots) {
-    return segments.map((segment) => (segment.kind === "literal" ? segment.text : slotToken(slots[segment.slot]))).join("");
+    return segments.map((segment) => (segment.kind === "literal" ? segment.text : slotToken(presentAt(slots, segment.slot, "template slots")))).join("");
 }
 /** The token value at a slot's position, with the literal affixes the template shows stripped off. */
 function coreAt(item, slot) {
@@ -65,12 +66,11 @@ function crossCheckIdentity(group, nameSlots, directorySlots, directoryValues) {
     for (const slot of nameSlots) {
         if (slot.distinctValues < 2)
             continue;
-        for (let k = 0; k < directoryValues.length; k++) {
-            const values = directoryValues[k];
-            const paired = directorySlots[k].distinctValues === slot.distinctValues;
+        for (const [k, values] of directoryValues.entries()) {
+            const paired = presentAt(directorySlots, k, "directory slots").distinctValues === slot.distinctValues;
             let matches = 0;
-            for (let i = 0; i < group.items.length; i++) {
-                const core = coreAt(group.items[i], slot);
+            for (const [i, item] of group.items.entries()) {
+                const core = coreAt(item, slot);
                 const segment = values[i] ?? "";
                 const alike = core === segment ||
                     (segment.includes(core) && (paired || core.length >= MIN_IDENTITY_TOKEN_LENGTH)) ||
@@ -101,8 +101,9 @@ function assembleMinedSet(group, path) {
         const at = variablePosition++;
         const values = members.map((member) => member.varValues[at] ?? "");
         const distinct = new Set(values);
-        if (distinct.size === 1) {
-            directorySegments.push({ kind: "literal", text: `${[...distinct][0]}/` });
+        const [only] = distinct;
+        if (only !== undefined && distinct.size === 1) {
+            directorySegments.push({ kind: "literal", text: `${only}/` });
             continue;
         }
         const slot = describeSlot(values, "directory", segment.index);
@@ -128,26 +129,28 @@ function finalizeSet(draft, index) {
     const id = `set-${index + 1}`;
     const slotIds = draft.slots.map((_, position) => `${id}.slot-${position + 1}`);
     const slots = draft.slots.map((slot, position) => ({
-        id: slotIds[position],
+        id: presentAt(slotIds, position, "slot ids"),
         location: slot.location,
         index: slot.index,
         tokenClass: slot.tokenClass,
-        ...(slot.width !== undefined ? { width: slot.width } : {}),
-        ...(slot.minLength !== undefined ? { minLength: slot.minLength, maxLength: slot.maxLength } : {}),
-        ...(slot.skeleton !== undefined ? { skeleton: slot.skeleton } : {}),
-        ...(slot.prefix !== undefined ? { prefix: slot.prefix } : {}),
-        ...(slot.suffix !== undefined ? { suffix: slot.suffix } : {}),
+        width: slot.width,
+        minLength: slot.minLength,
+        maxLength: slot.maxLength,
+        skeleton: slot.skeleton,
+        prefix: slot.prefix,
+        suffix: slot.suffix,
         distinctValues: slot.distinctValues,
         sampleValues: slot.sampleValues,
-        ...(slot.sameAs !== undefined ? { sameAsSlot: slotIds[slot.sameAs], crossCheckMismatches: slot.crossCheckMismatches ?? 0 } : {}),
+        sameAsSlot: slot.sameAs === undefined ? undefined : presentAt(slotIds, slot.sameAs, "slot ids"),
+        crossCheckMismatches: slot.sameAs === undefined ? undefined : (slot.crossCheckMismatches ?? 0),
     }));
-    const segments = draft.segments.map((segment) => segment.kind === "literal" ? { kind: "literal", text: segment.text } : { kind: "slot", slotId: slotIds[segment.slot] });
+    const segments = draft.segments.map((segment) => segment.kind === "literal" ? { kind: "literal", text: segment.text } : { kind: "slot", slotId: presentAt(slotIds, segment.slot, "slot ids") });
     const { members, completeness } = assessCompleteness(draft.members);
     return {
         set: {
             id,
             origin: draft.origin,
-            ...(draft.marker ? { marker: draft.marker } : {}),
+            marker: draft.marker,
             pathTemplate: draft.pathTemplate,
             segments,
             memberCount: members.length,
@@ -160,8 +163,8 @@ function finalizeSet(draft, index) {
             examplePaths: members.slice(0, MAX_EXAMPLE_PATHS).map((member) => member.path),
             members,
         },
-        values: draft.slots.map((slot, position) => [slotIds[position], slot.values]),
-        memberValues: draft.slots.map((slot, position) => [slotIds[position], slot.memberValues]),
+        values: draft.slots.map((slot, position) => [presentAt(slotIds, position, "slot ids"), slot.values]),
+        memberValues: draft.slots.map((slot, position) => [presentAt(slotIds, position, "slot ids"), slot.memberValues]),
     };
 }
 /**
@@ -236,8 +239,9 @@ export function detectSets(files, options = {}) {
         if (children.length === 0)
             return;
         for (const cluster of clusterChildren(children, options.contentSimilarity)) {
-            if (cluster.names.length === 1) {
-                descend(cluster.entries, [...path, { kind: "literal", name: cluster.names[0] }]);
+            const [name] = cluster.names;
+            if (name !== undefined && cluster.names.length === 1) {
+                descend(cluster.entries, [...path, { kind: "literal", name }]);
                 continue;
             }
             const next = cluster.entries.map((entry) => ({ node: entry.node, varValues: [...entry.varValues, entry.node.name] }));

package/dist/input-scan/enrich.d.ts

@@ -36,12 +36,12 @@ export declare const READOUT_CONCURRENCY = 8;
  */
 export declare const SANDBOX_CONTAINER_FORMATS: ReadonlySet<string>;
 /** One file to read a header from, and what the scan already knows about its bytes. */
-export interface ReadoutTargetSpec {
+export type ReadoutTargetSpec = {
     readonly path: string;
     readonly format: string;
     readonly wrapper?: string;
-}
-export interface ReadHeadersArgs {
+};
+export type ReadHeadersArgs = {
     readonly targets: readonly ReadoutTargetSpec[];
     readonly session: AgentSession;
     readonly fs: WorkspaceFilesystem;
@@ -52,8 +52,8 @@ export interface ReadHeadersArgs {
     readonly mountRoot: string;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
-}
-export interface EnrichShapesArgs {
+};
+export type EnrichShapesArgs = {
     readonly shapes: readonly FileShape[];
     readonly session: AgentSession;
     readonly fs: WorkspaceFilesystem;
@@ -64,7 +64,7 @@ export interface EnrichShapesArgs {
     readonly mountRoot: string;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
-}
+};
 /**
  * Read a header from each named file, keyed by path.
  *