@granular-software/sdk 0.4.18 → 0.4.19

package/dist/agent-harness.d.mts

@@ -0,0 +1,121 @@
+interface HarnessPromptLike {
+    id: string;
+    type?: string;
+    title?: string;
+    message?: string;
+}
+interface HarnessControllerBudgets {
+    maxIterations?: number;
+    maxNoProgressIterations?: number;
+}
+interface HarnessVerifierSnapshotInput {
+    finalCode?: string;
+    resultPreview?: string;
+    liveDoc: Record<string, unknown> | null;
+    projectionOptions?: HarnessProjectionOptions;
+}
+interface HarnessVerifierSnapshot {
+    codeDigest: string | null;
+    resultDigest: string | null;
+    heapDigest: string;
+    loopDigest: string;
+}
+interface HarnessContinuationDecision {
+    shouldContinue: boolean;
+    outcome: "continue" | "await_user" | "done" | "stalled" | "budget_exhausted";
+    reason: "workflow_closed" | "open_prompt" | "user_reply_complete" | "iteration_budget_exhausted" | "stalled_no_progress" | "progress_detected" | "no_prior_snapshot";
+    nextNoProgressCount: number;
+}
+interface GranularAgentSessionContext {
+    sandboxId?: string | null;
+    environmentId?: string | null;
+    userId?: string | null;
+    granularId?: string | null;
+    userName?: string | null;
+    domainRevision?: string | null;
+}
+interface GranularAgentToolInfo {
+    name: string;
+    description?: string;
+    className?: string;
+    static?: boolean;
+    ready?: boolean;
+}
+interface GranularAgentExecutionCheckpoint {
+    iteration?: number;
+    latestJobStatus?: string | null;
+    latestJobResult?: string | null;
+    latestJobError?: string | null;
+    latestActionSummary?: string[] | null;
+    controllerOutcome?: string | null;
+    controllerReason?: string | null;
+    noProgressCount?: number;
+}
+interface GranularAgentWorkflowFocus {
+    boundaryTimestamp: number;
+    boundaryReason: "session_start" | "last_closed_loop" | "request_start";
+    latestClosureId?: string | null;
+    activeTaskIds: string[];
+    openDecisionIds: string[];
+    openPromptIds: string[];
+    variableNames: string[];
+    listNames: string[];
+    entryPaths: string[];
+    recentActionSummary: string[];
+}
+interface GranularAgentHeapSummaryOptions {
+    focus?: Partial<Pick<GranularAgentWorkflowFocus, "variableNames" | "listNames" | "entryPaths">> | null;
+    maxVariables?: number;
+    maxLists?: number;
+    maxEntries?: number;
+}
+interface HarnessProjectionOptions {
+    boundaryTimestamp?: number | null;
+}
+interface BuildGranularAgentSystemPromptInput {
+    domainDocumentation?: string;
+    sessionContext?: GranularAgentSessionContext;
+    heapSummary?: string;
+    loopSummary?: string;
+    workflowSummary?: string;
+    tools?: GranularAgentToolInfo[];
+    checkpoint?: GranularAgentExecutionCheckpoint | null;
+}
+interface GeneratedJobCodeIssue {
+    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply";
+    severity: "error";
+    message: string;
+}
+declare function reviewGeneratedJobCode(code: string): GeneratedJobCodeIssue[];
+declare function getCurrentClosureId(liveDoc: Record<string, unknown> | null): string | null;
+declare function projectWorkflowFocus(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): GranularAgentWorkflowFocus;
+declare function projectWorkflowSummary(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): string;
+declare function hasOpenPrompt(liveDoc: Record<string, unknown> | null, pendingPrompts: HarnessPromptLike[]): boolean;
+declare function getExclusivePromptTarget<T extends HarnessPromptLike>(pendingPrompts: T[]): T | null;
+declare function projectLoopSummary(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): string;
+declare function projectHeapSummary(heap: unknown, options?: GranularAgentHeapSummaryOptions): string;
+declare function createHarnessVerifierSnapshot(input: HarnessVerifierSnapshotInput): HarnessVerifierSnapshot;
+declare function evaluateContinuation(input: {
+    iteration: number;
+    budgets?: HarnessControllerBudgets;
+    baselineClosureId: string | null;
+    currentClosureId: string | null;
+    liveDoc: Record<string, unknown> | null;
+    pendingPrompts: HarnessPromptLike[];
+    projectionOptions?: HarnessProjectionOptions;
+    latestResponseText?: string | null;
+    previousSnapshot?: HarnessVerifierSnapshot | null;
+    currentSnapshot: HarnessVerifierSnapshot;
+    previousNoProgressCount?: number;
+}): HarnessContinuationDecision;
+declare function buildContinuationInstruction(resultPreview?: string): string;
+declare function buildGranularAgentDomainBlock(domainDocumentation?: string): string;
+declare function buildGranularAgentSessionBlock(sessionContext?: GranularAgentSessionContext): string;
+declare function buildGranularAgentHeapBlock(heapSummary?: string): string;
+declare function buildGranularAgentLoopBlock(loopSummary?: string): string;
+declare function buildGranularAgentWorkflowBlock(workflowSummary?: string): string;
+declare function buildGranularAgentToolBlock(tools?: GranularAgentToolInfo[]): string;
+declare function buildGranularAgentCheckpointBlock(checkpoint?: GranularAgentExecutionCheckpoint | null): string;
+declare function buildGranularAgentSystemPrompt(input: BuildGranularAgentSystemPromptInput): string;
+
+export { type BuildGranularAgentSystemPromptInput, type GeneratedJobCodeIssue, type GranularAgentExecutionCheckpoint, type GranularAgentHeapSummaryOptions, type GranularAgentSessionContext, type GranularAgentToolInfo, type GranularAgentWorkflowFocus, type HarnessContinuationDecision, type HarnessControllerBudgets, type HarnessProjectionOptions, type HarnessPromptLike, type HarnessVerifierSnapshot, type HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode };

package/dist/agent-harness.d.ts

@@ -0,0 +1,121 @@
+interface HarnessPromptLike {
+    id: string;
+    type?: string;
+    title?: string;
+    message?: string;
+}
+interface HarnessControllerBudgets {
+    maxIterations?: number;
+    maxNoProgressIterations?: number;
+}
+interface HarnessVerifierSnapshotInput {
+    finalCode?: string;
+    resultPreview?: string;
+    liveDoc: Record<string, unknown> | null;
+    projectionOptions?: HarnessProjectionOptions;
+}
+interface HarnessVerifierSnapshot {
+    codeDigest: string | null;
+    resultDigest: string | null;
+    heapDigest: string;
+    loopDigest: string;
+}
+interface HarnessContinuationDecision {
+    shouldContinue: boolean;
+    outcome: "continue" | "await_user" | "done" | "stalled" | "budget_exhausted";
+    reason: "workflow_closed" | "open_prompt" | "user_reply_complete" | "iteration_budget_exhausted" | "stalled_no_progress" | "progress_detected" | "no_prior_snapshot";
+    nextNoProgressCount: number;
+}
+interface GranularAgentSessionContext {
+    sandboxId?: string | null;
+    environmentId?: string | null;
+    userId?: string | null;
+    granularId?: string | null;
+    userName?: string | null;
+    domainRevision?: string | null;
+}
+interface GranularAgentToolInfo {
+    name: string;
+    description?: string;
+    className?: string;
+    static?: boolean;
+    ready?: boolean;
+}
+interface GranularAgentExecutionCheckpoint {
+    iteration?: number;
+    latestJobStatus?: string | null;
+    latestJobResult?: string | null;
+    latestJobError?: string | null;
+    latestActionSummary?: string[] | null;
+    controllerOutcome?: string | null;
+    controllerReason?: string | null;
+    noProgressCount?: number;
+}
+interface GranularAgentWorkflowFocus {
+    boundaryTimestamp: number;
+    boundaryReason: "session_start" | "last_closed_loop" | "request_start";
+    latestClosureId?: string | null;
+    activeTaskIds: string[];
+    openDecisionIds: string[];
+    openPromptIds: string[];
+    variableNames: string[];
+    listNames: string[];
+    entryPaths: string[];
+    recentActionSummary: string[];
+}
+interface GranularAgentHeapSummaryOptions {
+    focus?: Partial<Pick<GranularAgentWorkflowFocus, "variableNames" | "listNames" | "entryPaths">> | null;
+    maxVariables?: number;
+    maxLists?: number;
+    maxEntries?: number;
+}
+interface HarnessProjectionOptions {
+    boundaryTimestamp?: number | null;
+}
+interface BuildGranularAgentSystemPromptInput {
+    domainDocumentation?: string;
+    sessionContext?: GranularAgentSessionContext;
+    heapSummary?: string;
+    loopSummary?: string;
+    workflowSummary?: string;
+    tools?: GranularAgentToolInfo[];
+    checkpoint?: GranularAgentExecutionCheckpoint | null;
+}
+interface GeneratedJobCodeIssue {
+    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply";
+    severity: "error";
+    message: string;
+}
+declare function reviewGeneratedJobCode(code: string): GeneratedJobCodeIssue[];
+declare function getCurrentClosureId(liveDoc: Record<string, unknown> | null): string | null;
+declare function projectWorkflowFocus(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): GranularAgentWorkflowFocus;
+declare function projectWorkflowSummary(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): string;
+declare function hasOpenPrompt(liveDoc: Record<string, unknown> | null, pendingPrompts: HarnessPromptLike[]): boolean;
+declare function getExclusivePromptTarget<T extends HarnessPromptLike>(pendingPrompts: T[]): T | null;
+declare function projectLoopSummary(liveDoc: Record<string, unknown> | null, pendingPrompts?: HarnessPromptLike[], options?: HarnessProjectionOptions): string;
+declare function projectHeapSummary(heap: unknown, options?: GranularAgentHeapSummaryOptions): string;
+declare function createHarnessVerifierSnapshot(input: HarnessVerifierSnapshotInput): HarnessVerifierSnapshot;
+declare function evaluateContinuation(input: {
+    iteration: number;
+    budgets?: HarnessControllerBudgets;
+    baselineClosureId: string | null;
+    currentClosureId: string | null;
+    liveDoc: Record<string, unknown> | null;
+    pendingPrompts: HarnessPromptLike[];
+    projectionOptions?: HarnessProjectionOptions;
+    latestResponseText?: string | null;
+    previousSnapshot?: HarnessVerifierSnapshot | null;
+    currentSnapshot: HarnessVerifierSnapshot;
+    previousNoProgressCount?: number;
+}): HarnessContinuationDecision;
+declare function buildContinuationInstruction(resultPreview?: string): string;
+declare function buildGranularAgentDomainBlock(domainDocumentation?: string): string;
+declare function buildGranularAgentSessionBlock(sessionContext?: GranularAgentSessionContext): string;
+declare function buildGranularAgentHeapBlock(heapSummary?: string): string;
+declare function buildGranularAgentLoopBlock(loopSummary?: string): string;
+declare function buildGranularAgentWorkflowBlock(workflowSummary?: string): string;
+declare function buildGranularAgentToolBlock(tools?: GranularAgentToolInfo[]): string;
+declare function buildGranularAgentCheckpointBlock(checkpoint?: GranularAgentExecutionCheckpoint | null): string;
+declare function buildGranularAgentSystemPrompt(input: BuildGranularAgentSystemPromptInput): string;
+
+export { type BuildGranularAgentSystemPromptInput, type GeneratedJobCodeIssue, type GranularAgentExecutionCheckpoint, type GranularAgentHeapSummaryOptions, type GranularAgentSessionContext, type GranularAgentToolInfo, type GranularAgentWorkflowFocus, type HarnessContinuationDecision, type HarnessControllerBudgets, type HarnessProjectionOptions, type HarnessPromptLike, type HarnessVerifierSnapshot, type HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode };