graphlit-client 1.0.20260301004 → 1.0.20260302001

package/dist/client.d.ts

@@ -1008,9 +1008,11 @@ declare class Graphlit {
      * @param includeDetails - Whether to include details, optional.
      * @param correlationId - The tenant correlation identifier, optional.
      * @param persona - The persona to use, optional.
+     * @param instructions - Per-turn instructions to inject into guidance, optional.
+     * @param scratchpad - Per-turn scratchpad text to inject, optional. Merged with conversation scratchpad.
      * @returns The formatted conversation.
      */
-    formatConversation(prompt: string, id?: string, specification?: Types.EntityReferenceInput, tools?: Types.ToolDefinitionInput[], systemPrompt?: string, includeDetails?: boolean, correlationId?: string, persona?: Types.EntityReferenceInput, instructions?: string): Promise<Types.FormatConversationMutation>;
+    formatConversation(prompt: string, id?: string, specification?: Types.EntityReferenceInput, tools?: Types.ToolDefinitionInput[], systemPrompt?: string, includeDetails?: boolean, correlationId?: string, persona?: Types.EntityReferenceInput, instructions?: string, scratchpad?: string): Promise<Types.FormatConversationMutation>;
     /**
      * Completes a conversation with an external LLM response.
      * @param completion - The completion text from the external LLM.
@@ -1053,9 +1055,11 @@ declare class Graphlit {
      * @param includeDetails - Whether to include details, optional.
      * @param correlationId - The tenant correlation identifier, optional.
      * @param persona - The persona to use, optional.
+     * @param instructions - Per-turn instructions to inject into guidance, optional.
+     * @param scratchpad - Per-turn scratchpad text to inject, optional. Merged with conversation scratchpad.
      * @returns The conversation response.
      */
-    promptConversation(prompt: string, id?: string, specification?: Types.EntityReferenceInput, mimeType?: string, data?: string, tools?: Types.ToolDefinitionInput[], requireTool?: boolean, systemPrompt?: string, includeDetails?: boolean, correlationId?: string, persona?: Types.EntityReferenceInput, instructions?: string): Promise<Types.PromptConversationMutation>;
+    promptConversation(prompt: string, id?: string, specification?: Types.EntityReferenceInput, mimeType?: string, data?: string, tools?: Types.ToolDefinitionInput[], requireTool?: boolean, systemPrompt?: string, includeDetails?: boolean, correlationId?: string, persona?: Types.EntityReferenceInput, instructions?: string, scratchpad?: string): Promise<Types.PromptConversationMutation>;
     /**
      * Continues a conversation with tool responses.
      * @param id - The conversation ID.

package/dist/client.js

@@ -1863,9 +1863,11 @@ class Graphlit {
      * @param includeDetails - Whether to include details, optional.
      * @param correlationId - The tenant correlation identifier, optional.
      * @param persona - The persona to use, optional.
+     * @param instructions - Per-turn instructions to inject into guidance, optional.
+     * @param scratchpad - Per-turn scratchpad text to inject, optional. Merged with conversation scratchpad.
      * @returns The formatted conversation.
      */
-    async formatConversation(prompt, id, specification, tools, systemPrompt, includeDetails, correlationId, persona, instructions) {
+    async formatConversation(prompt, id, specification, tools, systemPrompt, includeDetails, correlationId, persona, instructions, scratchpad) {
         return this.mutateAndCheckError(Documents.FormatConversation, {
             prompt: prompt,
             id: id,
@@ -1876,6 +1878,7 @@ class Graphlit {
             includeDetails: includeDetails,
             correlationId: correlationId,
             instructions: instructions,
+            scratchpad: scratchpad,
         });
     }
     /**
@@ -1943,9 +1946,11 @@ class Graphlit {
      * @param includeDetails - Whether to include details, optional.
      * @param correlationId - The tenant correlation identifier, optional.
      * @param persona - The persona to use, optional.
+     * @param instructions - Per-turn instructions to inject into guidance, optional.
+     * @param scratchpad - Per-turn scratchpad text to inject, optional. Merged with conversation scratchpad.
      * @returns The conversation response.
      */
-    async promptConversation(prompt, id, specification, mimeType, data, tools, requireTool, systemPrompt, includeDetails, correlationId, persona, instructions) {
+    async promptConversation(prompt, id, specification, mimeType, data, tools, requireTool, systemPrompt, includeDetails, correlationId, persona, instructions, scratchpad) {
         return this.mutateAndCheckError(Documents.PromptConversation, {
             prompt: prompt,
             id: id,
@@ -1959,6 +1964,7 @@ class Graphlit {
             includeDetails: includeDetails,
             correlationId: correlationId,
             instructions: instructions,
+            scratchpad: scratchpad,
         });
     }
     /**
@@ -5075,7 +5081,7 @@ class Graphlit {
                 });
                 // Start the streaming conversation
                 // fullSpec is guaranteed non-null here — the !fullSpec check above returns early
-                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, options?.contextStrategy, options?.instructions);
+                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, options?.contextStrategy, options?.instructions, options?.scratchpad);
             }, abortSignal);
         }
         catch (error) {
@@ -5121,7 +5127,7 @@ class Graphlit {
     /**
      * Execute the streaming agent workflow with tool calling loop
      */
-    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, contextStrategy, instructions) {
+    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, contextStrategy, instructions, scratchpad) {
         // Collects artifact content IDs from tool handlers (e.g. code_execution).
         // Handlers register async ingestion promises; we await all of them before
         // completeConversation so the IDs are available without blocking the LLM.
@@ -5141,7 +5147,7 @@ class Graphlit {
             conversationId,
         });
         // Format conversation once at the beginning
-        const formatResponse = await this.formatConversation(prompt, conversationId, { id: specification.id }, tools, undefined, true, correlationId, persona, instructions);
+        const formatResponse = await this.formatConversation(prompt, conversationId, { id: specification.id }, tools, undefined, true, correlationId, persona, instructions, scratchpad);
         const formattedMessage = formatResponse.formatConversation?.message;
         const conversationHistory = formatResponse.formatConversation?.details?.messages;
         if (!formattedMessage?.message) {
@@ -5952,6 +5958,7 @@ class Graphlit {
             // Resolve or create Agent entity
             let agentSpec = specification;
             let agentFilter;
+            let agentScratchpad;
             if (agentId) {
                 const agentResponse = await this.getAgent(agentId, options?.correlationId);
                 const agent = agentResponse.agent;
@@ -5968,6 +5975,9 @@ class Graphlit {
                 if (agent.filter) {
                     agentFilter = agent.filter;
                 }
+                if (agent.scratchpad) {
+                    agentScratchpad = agent.scratchpad;
+                }
             }
             else {
                 // Create ephemeral agent
@@ -6134,7 +6144,7 @@ class Graphlit {
                 }
                 else {
                     // Formatted path: call formatConversation
-                    const formatResponse = await this.formatConversation(turn === 0 ? prompt : "Continue.", conversationId, agentSpec, allTools, undefined, true, options?.correlationId, options?.persona, turnInstructions);
+                    const formatResponse = await this.formatConversation(turn === 0 ? prompt : "Continue.", conversationId, agentSpec, allTools, undefined, true, options?.correlationId, options?.persona, turnInstructions, agentScratchpad);
                     const formattedMessage = formatResponse.formatConversation?.message;
                     const conversationHistory = formatResponse.formatConversation?.details?.messages;
                     const formatDetails = formatResponse.formatConversation?.details;

package/dist/generated/graphql-documents.js

@@ -4827,6 +4827,7 @@ export const CompleteConversation = gql `
       formattedSources
       formattedObservables
       formattedInstructions
+      formattedScratchpad
       formattedTools
       formattedPersona
       specification
@@ -5174,6 +5175,7 @@ export const ContinueConversation = gql `
       formattedSources
       formattedObservables
       formattedInstructions
+      formattedScratchpad
       formattedTools
       formattedPersona
       specification
@@ -5367,7 +5369,7 @@ export const DeleteConversations = gql `
 }
     `;
 export const FormatConversation = gql `
-    mutation FormatConversation($prompt: String!, $id: ID, $specification: EntityReferenceInput, $persona: EntityReferenceInput, $tools: [ToolDefinitionInput!], $systemPrompt: String, $includeDetails: Boolean, $correlationId: String, $instructions: String) {
+    mutation FormatConversation($prompt: String!, $id: ID, $specification: EntityReferenceInput, $persona: EntityReferenceInput, $tools: [ToolDefinitionInput!], $systemPrompt: String, $includeDetails: Boolean, $correlationId: String, $instructions: String, $scratchpad: String) {
   formatConversation(
     prompt: $prompt
     id: $id
@@ -5378,6 +5380,7 @@ export const FormatConversation = gql `
     includeDetails: $includeDetails
     correlationId: $correlationId
     instructions: $instructions
+    scratchpad: $scratchpad
   ) {
     conversation {
       id
@@ -5572,6 +5575,7 @@ export const FormatConversation = gql `
       formattedSources
       formattedObservables
       formattedInstructions
+      formattedScratchpad
       formattedTools
       formattedPersona
       specification
@@ -6292,7 +6296,7 @@ export const Prompt = gql `
 }
     `;
 export const PromptConversation = gql `
-    mutation PromptConversation($prompt: String!, $mimeType: String, $data: String, $id: ID, $specification: EntityReferenceInput, $persona: EntityReferenceInput, $systemPrompt: String, $tools: [ToolDefinitionInput!], $requireTool: Boolean, $includeDetails: Boolean, $correlationId: String, $instructions: String) {
+    mutation PromptConversation($prompt: String!, $mimeType: String, $data: String, $id: ID, $specification: EntityReferenceInput, $persona: EntityReferenceInput, $systemPrompt: String, $tools: [ToolDefinitionInput!], $requireTool: Boolean, $includeDetails: Boolean, $correlationId: String, $instructions: String, $scratchpad: String) {
   promptConversation(
     prompt: $prompt
     id: $id
@@ -6306,6 +6310,7 @@ export const PromptConversation = gql `
     includeDetails: $includeDetails
     correlationId: $correlationId
     instructions: $instructions
+    scratchpad: $scratchpad
   ) {
     conversation {
       id
@@ -6500,6 +6505,7 @@ export const PromptConversation = gql `
       formattedSources
       formattedObservables
       formattedInstructions
+      formattedScratchpad
       formattedTools
       formattedPersona
       specification

package/dist/generated/graphql-types.d.ts

@@ -3711,6 +3711,8 @@ export type Conversation = {
     persona?: Maybe<Persona>;
     /** The relevance score of the conversation. */
     relevance?: Maybe<Scalars['Float']['output']>;
+    /** The conversation scratchpad, for storing harness working memory as raw text. */
+    scratchpad?: Maybe<Scalars['String']['output']>;
     /** The LLM specification used by this conversation. */
     specification?: Maybe<Specification>;
     /** The state of the conversation (i.e. created, finished). */
@@ -3753,6 +3755,8 @@ export type ConversationDetails = {
     formattedObservables?: Maybe<Scalars['String']['output']>;
     /** The formatted persona prompt. */
     formattedPersona?: Maybe<Scalars['String']['output']>;
+    /** The formatted scratchpad. */
+    formattedScratchpad?: Maybe<Scalars['String']['output']>;
     /** The formatted sources. */
     formattedSources?: Maybe<Scalars['String']['output']>;
     /** The formatted LLM tools. */
@@ -3864,6 +3868,8 @@ export type ConversationInput = {
     name: Scalars['String']['input'];
     /** The persona used by this conversation, optional. */
     persona?: InputMaybe<EntityReferenceInput>;
+    /** The conversation scratchpad, for storing harness working memory as raw text. */
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
     /** The LLM specification used by this conversation, optional. */
     specification?: InputMaybe<EntityReferenceInput>;
     /** The tool calling definitions. */
@@ -4166,6 +4172,8 @@ export type ConversationUpdateInput = {
     name?: InputMaybe<Scalars['String']['input']>;
     /** The persona used by this conversation, optional. */
     persona?: InputMaybe<EntityReferenceInput>;
+    /** The conversation scratchpad, for storing harness working memory as raw text. */
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
     /** The LLM specification used by this conversation, optional. */
     specification?: InputMaybe<EntityReferenceInput>;
     /** The tool calling definitions. */
@@ -15045,6 +15053,7 @@ export type MutationFormatConversationArgs = {
     instructions?: InputMaybe<Scalars['String']['input']>;
     persona?: InputMaybe<EntityReferenceInput>;
     prompt: Scalars['String']['input'];
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
     specification?: InputMaybe<EntityReferenceInput>;
     systemPrompt?: InputMaybe<Scalars['String']['input']>;
     tools?: InputMaybe<Array<ToolDefinitionInput>>;
@@ -15172,6 +15181,7 @@ export type MutationPromptConversationArgs = {
     persona?: InputMaybe<EntityReferenceInput>;
     prompt: Scalars['String']['input'];
     requireTool?: InputMaybe<Scalars['Boolean']['input']>;
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
     specification?: InputMaybe<EntityReferenceInput>;
     systemPrompt?: InputMaybe<Scalars['String']['input']>;
     tools?: InputMaybe<Array<ToolDefinitionInput>>;
@@ -28314,6 +28324,7 @@ export type CompleteConversationMutation = {
             formattedSources?: string | null;
             formattedObservables?: string | null;
             formattedInstructions?: string | null;
+            formattedScratchpad?: string | null;
             formattedTools?: string | null;
             formattedPersona?: string | null;
             specification?: string | null;
@@ -28689,6 +28700,7 @@ export type ContinueConversationMutation = {
             formattedSources?: string | null;
             formattedObservables?: string | null;
             formattedInstructions?: string | null;
+            formattedScratchpad?: string | null;
             formattedTools?: string | null;
             formattedPersona?: string | null;
             specification?: string | null;
@@ -28915,6 +28927,7 @@ export type FormatConversationMutationVariables = Exact<{
     includeDetails?: InputMaybe<Scalars['Boolean']['input']>;
     correlationId?: InputMaybe<Scalars['String']['input']>;
     instructions?: InputMaybe<Scalars['String']['input']>;
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
 }>;
 export type FormatConversationMutation = {
     __typename?: 'Mutation';
@@ -29131,6 +29144,7 @@ export type FormatConversationMutation = {
             formattedSources?: string | null;
             formattedObservables?: string | null;
             formattedInstructions?: string | null;
+            formattedScratchpad?: string | null;
             formattedTools?: string | null;
             formattedPersona?: string | null;
             specification?: string | null;
@@ -29960,6 +29974,7 @@ export type PromptConversationMutationVariables = Exact<{
     includeDetails?: InputMaybe<Scalars['Boolean']['input']>;
     correlationId?: InputMaybe<Scalars['String']['input']>;
     instructions?: InputMaybe<Scalars['String']['input']>;
+    scratchpad?: InputMaybe<Scalars['String']['input']>;
 }>;
 export type PromptConversationMutation = {
     __typename?: 'Mutation';
@@ -30176,6 +30191,7 @@ export type PromptConversationMutation = {
             formattedSources?: string | null;
             formattedObservables?: string | null;
             formattedInstructions?: string | null;
+            formattedScratchpad?: string | null;
             formattedTools?: string | null;
             formattedPersona?: string | null;
             specification?: string | null;

package/dist/types/agent.d.ts

@@ -68,6 +68,8 @@ export interface StreamAgentOptions {
     contextStrategy?: ContextStrategy;
     /** Harness-injected instructions appended to the formatted conversation (e.g. wind-down, stuck intervention). */
     instructions?: string;
+    /** Harness-injected scratchpad text, merged with conversation scratchpad. Placed right before user-prompt. */
+    scratchpad?: string;
 }
 export interface ToolCallResult {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20260301004",
+  "version": "1.0.20260302001",
   "description": "Graphlit API Client for TypeScript",
   "type": "module",
   "main": "./dist/client.js",