@applica-software-guru/persona-sdk 0.1.101 → 0.1.103

package/src/agents/types.ts

@@ -9,7 +9,6 @@ export type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
 
 export type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
 
-export type StmType = 'simple' | 'summary' | 'compact';
 
 export type ToolType = 'remote' | 'local';
 
@@ -43,6 +42,8 @@ export interface ModelConfiguration {
   reasoningEffort?: ReasoningEffort;
   /** Maximum number of output tokens to generate. Undefined = provider default. */
   maxOutputTokens?: number;
+  /** Total context window (input) of the model, in tokens. Used by compaction. Undefined = default (128000). */
+  contextWindow?: number;
   /** Override the per-provider default API key (env var) when set. */
   apiKey?: string;
   /** Override the per-provider default base URL when set. */
@@ -245,30 +246,15 @@ export interface ToolkitConfiguration {
   tools?: Tool[];
 }
 
-export interface StmConfiguration {
-  type?: StmType;
-  maxMessages?: number;
-  includeToolCalls?: boolean;
-  model?: ModelConfiguration;
-  maxNumberOfWords?: number;
-  keepLastNObservations?: number;
-  maskingThreshold?: number;
-  summaryThreshold?: number;
-  maxContextTokens?: number;
-}
-
-export interface ContextManagementConfiguration {
+export interface CompactionConfiguration {
+  /** Enable automatic context compaction. Default: true. */
   enabled?: boolean;
-  maxContextTokens?: number;
-  summarizationThreshold?: number;
-  keepLastNIterations?: number;
-  keepFirstMessage?: boolean;
-  maxToolCallsBeforeCompaction?: number;
-  useLlmCompaction?: boolean;
-  maxSummaryWords?: number;
-  truncationEnabled?: boolean;
-  maxObservationTokens?: number;
-  compactionModel?: ModelConfiguration;
+  /** Headroom kept free below the context window. Default: 16384. */
+  reserveTokens?: number;
+  /** Token budget of recent conversation never summarized. Default: 20000. */
+  keepRecentTokens?: number;
+  /** Model used to generate the summary. Defaults to the agent's main model. */
+  model?: ModelConfiguration;
 }
 
 export interface Revision {
@@ -307,8 +293,7 @@ export interface Agent {
   network?: NetworkConfiguration;
   features?: Feature[];
   toolkit?: ToolkitConfiguration;
-  shortTermMemory?: StmConfiguration;
-  contextManagement?: ContextManagementConfiguration;
+  compaction?: CompactionConfiguration;
   attachmentsPreprocessor?: AttachmentsPreprocessorConfiguration;
   responseSchema?: Record<string, unknown>;
   verboseErrors?: boolean;
@@ -339,8 +324,7 @@ export interface AgentCreateRequest {
   network?: NetworkConfiguration;
   features?: Feature[];
   toolkit?: ToolkitConfiguration;
-  shortTermMemory?: StmConfiguration;
-  contextManagement?: ContextManagementConfiguration;
+  compaction?: CompactionConfiguration;
   attachmentsPreprocessor?: AttachmentsPreprocessorConfiguration;
   responseSchema?: Record<string, unknown>;
   verboseErrors?: boolean;

package/src/index.ts

@@ -47,14 +47,12 @@ export type {
   ToolRemoteConfig,
   ToolDefinition,
   ToolkitConfiguration,
-  StmConfiguration,
-  StmType,
+  CompactionConfiguration,
   Revision,
   AgentType,
   ReasoningEffort,
   ModelProvider,
   CollaborationMode,
-  ContextManagementConfiguration,
   AttachmentsPreprocessorConfiguration,
   AttachmentsPreprocessorImageHandling,
 } from './agents/types';
@@ -95,6 +93,7 @@ export type {
 } from './knowledges/types';
 export { WorkflowsApi } from './workflows/workflows-api';
 export { WorkflowExecutionsApi } from './workflows/workflow-executions-api';
+export { HumanTasksApi } from './workflows/human-tasks-api';
 export type {
   Workflow,
   Node,
@@ -114,6 +113,7 @@ export type {
   VariableDirection,
   WorkflowResult,
   ExecuteRequest,
+  HumanTask,
   AgentValue,
   ContentItem,
   ContentItemFile,

package/src/sessions/types.ts

@@ -66,6 +66,8 @@ export interface Message {
   task?: Record<string, unknown>;
   sender?: string;
   thought?: boolean;
+  /** True when this message is a context-compaction summary (injected by compaction). */
+  isCompactionSummary?: boolean;
 }
 
 export interface AgentResponse {

package/src/values/values-api.ts

@@ -42,10 +42,6 @@ export class ValuesApi extends HttpApi {
     return this.httpGet<string[]>('/values/synthesizers/' + synthesizerName + '/voices');
   }
 
-  async getStmTypes(): Promise<string[]> {
-    return this.httpGet<string[]>('/values/stm-types');
-  }
-
   async getDocumentExtractors(): Promise<string[]> {
     return this.httpGet<string[]>('/values/document-extractors');
   }

package/src/workflows/human-tasks-api.ts

@@ -0,0 +1,44 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { HumanTask } from './types';
+
+/**
+ * Human-in-the-loop tasks. A task is created when a workflow step
+ * suspends waiting for a human (a declared `human` node or an agent
+ * escalation); responding to it resumes the run. Lives on the workflows
+ * service.
+ */
+export class HumanTasksApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  /** The project's human-task inbox. */
+  async list(
+    filters: {
+      status?: string;
+      assignee?: string;
+      workflowId?: string;
+      executionId?: string;
+      page?: number;
+      size?: number;
+    } = {},
+  ): Promise<Paginated<HumanTask>> {
+    const { page, size } = this.normalizePageParams(filters.page, filters.size ?? 50);
+    const params: Record<string, unknown> = { page, size };
+    if (filters.status ?? 'pending') params.status = filters.status ?? 'pending';
+    if (filters.assignee) params.assignee = filters.assignee;
+    if (filters.workflowId) params.workflowId = filters.workflowId;
+    if (filters.executionId) params.executionId = filters.executionId;
+    return this.httpGet<Paginated<HumanTask>>('/human-tasks', params);
+  }
+
+  /** Answer a pending human task, resuming the suspended workflow execution. */
+  async respond(humanTaskId: string, response: unknown, respondedBy?: string): Promise<HumanTask> {
+    return this.httpPost<HumanTask>('/human-tasks/' + humanTaskId + '/respond', {
+      response,
+      respondedBy,
+    });
+  }
+}

package/src/workflows/types.ts

@@ -136,6 +136,29 @@ export interface ExecuteRequest {
   userId?: string;
   initialData?: Record<string, unknown>;
   callbackUrl?: string;
+  eventsHook?: string;
+}
+
+export interface HumanTask {
+  id: string;
+  projectId?: string;
+  workflowId?: string;
+  workflowName?: string;
+  executionId?: string;
+  nodeId?: string;
+  stepId?: string;
+  origin?: 'node' | 'agent_escalation';
+  question?: string;
+  payload?: Record<string, unknown>;
+  assignee?: string;
+  role?: string;
+  status: string;
+  response?: unknown;
+  respondedBy?: string;
+  respondedAt?: string;
+  createdAt?: string;
+  timeoutAt?: string;
+  sessionCode?: string;
 }
 
 export interface Workflow {

package/src/workflows/workflow-executions-api.ts

@@ -25,4 +25,70 @@ export class WorkflowExecutionsApi extends HttpApi {
   async queue(workflowId: string, request: ExecuteRequest): Promise<Execution> {
     return this.httpPost<Execution>('/workflows/' + workflowId + '/executions/queue', request);
   }
+
+  /** Runs across all workflows in the project (filter by status/workflow/date). */
+  async listRuns(filters: {
+    status?: string;
+    workflowId?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    page?: number;
+    size?: number;
+  } = {}): Promise<Paginated<Execution>> {
+    const { page, size } = this.normalizePageParams(filters.page, filters.size);
+    const params: Record<string, unknown> = { page, size };
+    if (filters.status) params.status = filters.status;
+    if (filters.workflowId) params.workflowId = filters.workflowId;
+    if (filters.dateFrom) params.dateFrom = filters.dateFrom;
+    if (filters.dateTo) params.dateTo = filters.dateTo;
+    return this.httpGet<Paginated<Execution>>('/executions', params);
+  }
+
+  /** Request cancellation of a running/waiting execution (cascades to sub-workflows). */
+  async cancel(workflowId: string, executionId: string): Promise<Execution> {
+    return this.httpPost<Execution>(
+      '/workflows/' + workflowId + '/executions/' + executionId + '/cancel',
+      {},
+    );
+  }
+
+  /** Re-run an execution from a given node. mode: 'reuse_outputs' | 'fresh'. */
+  async rerun(
+    workflowId: string,
+    executionId: string,
+    fromNodeId: string,
+    mode: 'reuse_outputs' | 'fresh' = 'reuse_outputs',
+  ): Promise<Execution> {
+    return this.httpPost<Execution>(
+      '/workflows/' + workflowId + '/executions/' + executionId + '/rerun',
+      { fromNodeId, mode },
+    );
+  }
+
+  /** Execute a single node in isolation with the given inputs (debugging). */
+  async dryRunNode(
+    workflowId: string,
+    nodeId: string,
+    inputs: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown>> {
+    return this.httpPost<Record<string, unknown>>(
+      '/workflows/' + workflowId + '/nodes/' + nodeId + '/dry-run',
+      { inputs },
+    );
+  }
+
+  /** Normalized action trace of an agent step (reasoning, tool calls, messages). */
+  async stepTrace(
+    workflowId: string,
+    executionId: string,
+    stepId: string,
+    page?: number,
+    size?: number,
+  ): Promise<Record<string, unknown>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size ?? 200);
+    return this.httpGet<Record<string, unknown>>(
+      '/workflows/' + workflowId + '/executions/' + executionId + '/steps/' + stepId + '/trace',
+      { page: p, size: s },
+    );
+  }
 }

package/src/workflows/workflows-api.ts

@@ -4,6 +4,7 @@ import { AuthenticationProvider } from '../auth/authentication-provider';
 import { Revision } from '../revisions/types';
 import { Workflow } from './types';
 import { WorkflowExecutionsApi } from './workflow-executions-api';
+import { HumanTasksApi } from './human-tasks-api';
 
 export class WorkflowsApi extends HttpApi {
   constructor(baseUrl: string, auth: string | AuthenticationProvider) {
@@ -38,6 +39,10 @@ export class WorkflowsApi extends HttpApi {
     return new WorkflowExecutionsApi(this.getBaseUrl(), this.getAuthProvider());
   }
 
+  humanTasks(): HumanTasksApi {
+    return new HumanTasksApi(this.getBaseUrl(), this.getAuthProvider());
+  }
+
   async listRevisions(workflowId: string): Promise<Revision[]> {
     return this.httpGet<Revision[]>('/workflows/' + workflowId + '/revisions');
   }