@tenex-chat/backend 0.9.5 → 0.9.6

package/src/agents/execution/StreamExecutionHandler.ts

@@ -11,12 +11,10 @@ import {
     type ChunkTypeChangeEvent,
     type CompleteEvent,
     type ContentEvent,
-    type RawChunkEvent,
     type ReasoningEvent,
     type SessionCapturedEvent,
     type StreamErrorEvent,
 } from "@/llm/types";
-import { streamPublisher } from "@/llm";
 import { PROVIDER_IDS } from "@/llm/providers/provider-ids";
 import { shortenConversationId } from "@/utils/conversation-id";
 import type { EventContext } from "@/nostr/types";
@@ -68,8 +66,15 @@ export interface StreamExecutionConfig {
  * Handles all LLM stream event processing and coordination
  */
 export class StreamExecutionHandler {
+    private static readonly STREAM_TEXT_DELTA_THROTTLE_MS = 1000;
+
     private contentBuffer = "";
     private reasoningBuffer = "";
+    private streamTextDeltaBuffer = "";
+    private streamTextDeltaSequence = 0;
+    private streamTextDeltaTimer: NodeJS.Timeout | undefined;
+    private streamTextDeltaFlushChain: Promise<void> = Promise.resolve();
+    private streamTextDeltaEventContext: EventContext | undefined;
     private result: StreamExecutionResult | undefined;
     private lastUsedVariant: string | undefined;
     private currentModel: LanguageModel | undefined;
@@ -134,19 +139,6 @@ export class StreamExecutionHandler {
                 });
             }
 
-            // Subscribe to raw chunks and forward to local streaming socket
-            llmService.on("raw-chunk", (event: RawChunkEvent) => {
-                logger.debug("[StreamExecutionHandler] raw-chunk received", {
-                    chunkType: event.chunk.type,
-                    agentPubkey: context.agent.pubkey.substring(0, 8),
-                });
-                streamPublisher.write({
-                    agent_pubkey: context.agent.pubkey,
-                    conversation_id: context.conversationId,
-                    data: event.chunk,
-                });
-            });
-
             // Create callbacks using extracted factory functions
             const prepareStep = createPrepareStep({
                 context,
@@ -182,6 +174,11 @@ export class StreamExecutionHandler {
                 prepareStep,
             });
 
+            await this.flushStreamTextDeltas({
+                force: true,
+                reason: "stream-return",
+            });
+
             // DIAGNOSTIC: Track when stream() returns with process state comparison
             const streamCallEndTime = Date.now();
             const streamCallDuration = streamCallEndTime - streamCallStartTime;
@@ -284,11 +281,13 @@ export class StreamExecutionHandler {
         const { context, llmService, toolTracker, toolsObject } = this.config;
         const agentPublisher = context.agentPublisher;
         const eventContext = this.createEventContext();
+        this.streamTextDeltaEventContext = eventContext;
         const ralNumber = this.config.ralNumber;
 
         llmService.on("content", (event: ContentEvent) => {
             process.stdout.write(chalk.white(event.delta));
             this.contentBuffer += event.delta;
+            this.enqueueStreamTextDelta(event.delta);
         });
 
         llmService.on("reasoning", (event: ReasoningEvent) => {
@@ -301,6 +300,10 @@ export class StreamExecutionHandler {
                 await this.flushReasoningBuffer();
             }
             if (event.from === "text-delta") {
+                await this.flushStreamTextDeltas({
+                    force: true,
+                    reason: "chunk-type-change",
+                });
                 await this.flushContentBuffer();
             }
         });
@@ -312,7 +315,12 @@ export class StreamExecutionHandler {
             "ral.number": ralNumber,
         });
 
-        llmService.on("complete", (event: CompleteEvent) => {
+        llmService.on("complete", async (event: CompleteEvent) => {
+            await this.flushStreamTextDeltas({
+                force: true,
+                reason: "complete",
+            });
+
             const completeReceivedTime = Date.now();
             const timeSinceRegistration = completeReceivedTime - completeListenerRegisteredAt;
             this.executionSpan?.addEvent("executor.complete_received", {
@@ -349,6 +357,11 @@ export class StreamExecutionHandler {
         });
 
         llmService.on("stream-error", async (event: StreamErrorEvent) => {
+            await this.flushStreamTextDeltas({
+                force: true,
+                reason: "stream-error",
+            });
+
             const errorReceivedTime = Date.now();
             const timeSinceRegistration = errorReceivedTime - completeListenerRegisteredAt;
             this.executionSpan?.addEvent("executor.stream_error_received", {
@@ -500,6 +513,11 @@ export class StreamExecutionHandler {
         const { context } = this.config;
         const ralNumber = this.config.ralNumber;
 
+        await this.flushStreamTextDeltas({
+            force: true,
+            reason: "handle-stream-error",
+        });
+
         if (abortSignal.aborted) {
             this.executionSpan?.addEvent("executor.aborted_by_stop_signal", {
                 "ral.number": ralNumber,
@@ -565,6 +583,8 @@ export class StreamExecutionHandler {
         const ralNumber = this.config.ralNumber;
         const ralRegistry = RALRegistry.getInstance();
 
+        this.clearStreamTextDeltaTimer();
+
         ralRegistry.endLLMStream(context.agent.pubkey, context.conversationId, ralNumber);
         ralRegistry.setStreaming(context.agent.pubkey, context.conversationId, ralNumber, false);
 
@@ -576,4 +596,78 @@ export class StreamExecutionHandler {
             clearLLMSpanId(currentSpan.spanContext().traceId);
         }
     }
+
+    private enqueueStreamTextDelta(delta: string): void {
+        if (delta.length === 0) {
+            return;
+        }
+
+        this.streamTextDeltaBuffer += delta;
+        if (this.streamTextDeltaTimer) {
+            return;
+        }
+
+        this.streamTextDeltaTimer = setTimeout(() => {
+            this.streamTextDeltaTimer = undefined;
+            void this.flushStreamTextDeltas({
+                force: false,
+                reason: "throttle-window",
+            });
+        }, StreamExecutionHandler.STREAM_TEXT_DELTA_THROTTLE_MS);
+    }
+
+    private clearStreamTextDeltaTimer(): void {
+        if (this.streamTextDeltaTimer) {
+            clearTimeout(this.streamTextDeltaTimer);
+            this.streamTextDeltaTimer = undefined;
+        }
+    }
+
+    private flushStreamTextDeltas(options: { force: boolean; reason: string }): Promise<void> {
+        this.streamTextDeltaFlushChain = this.streamTextDeltaFlushChain
+            .then(async () => {
+                if (options.force) {
+                    this.clearStreamTextDeltaTimer();
+                }
+
+                if (this.streamTextDeltaBuffer.length === 0) {
+                    return;
+                }
+
+                const eventContext = this.streamTextDeltaEventContext;
+                if (!eventContext) {
+                    this.streamTextDeltaBuffer = "";
+                    return;
+                }
+
+                const deltaToPublish = this.streamTextDeltaBuffer;
+                this.streamTextDeltaBuffer = "";
+                this.streamTextDeltaSequence += 1;
+
+                this.executionSpan?.addEvent("executor.stream_delta_flush", {
+                    "delta.sequence": this.streamTextDeltaSequence,
+                    "delta.length": deltaToPublish.length,
+                    "delta.reason": options.reason,
+                    "ral.number": this.config.ralNumber,
+                });
+
+                await this.config.context.agentPublisher.streamTextDelta(
+                    {
+                        delta: deltaToPublish,
+                        sequence: this.streamTextDeltaSequence,
+                    },
+                    eventContext
+                );
+            })
+            .catch((error) => {
+                logger.warn("[StreamExecutionHandler] Failed to flush stream text deltas", {
+                    error: formatAnyError(error),
+                    conversationId: this.config.context.conversationId.substring(0, 12),
+                    agent: this.config.context.agent.slug,
+                    ralNumber: this.config.ralNumber,
+                });
+            });
+
+        return this.streamTextDeltaFlushChain;
+    }
 }

package/src/agents/execution/StreamSetup.ts

@@ -126,15 +126,25 @@ export async function setupStreamExecution(
                     content: injection.content,
                 });
             } else {
-                conversationStore.addMessage({
-                    pubkey: context.triggeringEvent.pubkey,
-                    ral: ralNumber,
-                    content: injection.content,
-                    messageType: "text",
-                    targetedPubkeys: [context.agent.pubkey],
-                    senderPubkey: injection.senderPubkey,
-                    eventId: injection.eventId,
-                });
+                const relocated = injection.eventId
+                    ? conversationStore.relocateToEnd(injection.eventId, {
+                          ral: ralNumber,
+                          senderPubkey: injection.senderPubkey,
+                          targetedPubkeys: [context.agent.pubkey],
+                      })
+                    : false;
+
+                if (!relocated) {
+                    conversationStore.addMessage({
+                        pubkey: context.triggeringEvent.pubkey,
+                        ral: ralNumber,
+                        content: injection.content,
+                        messageType: "text",
+                        targetedPubkeys: [context.agent.pubkey],
+                        senderPubkey: injection.senderPubkey,
+                        eventId: injection.eventId,
+                    });
+                }
             }
         }
 

package/src/agents/execution/ToolEventHandlers.ts

@@ -20,6 +20,106 @@ import type { FullRuntimeContext } from "./types";
 import { getHeuristicEngine } from "@/services/heuristics";
 import { buildHeuristicContext } from "@/services/heuristics/ContextBuilder";
 
+const TRANSCRIPT_RAW_ARGS_MAX_LENGTH = 200;
+
+function truncateForTranscript(value: string, maxLength: number): string {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    const truncatedChars = value.length - maxLength;
+    return `${value.slice(0, maxLength)}... [truncated ${truncatedChars} chars]`;
+}
+
+function normalizeTranscriptAttrName(value: string): string {
+    const normalized = value.replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+    if (/^[a-zA-Z_]/.test(normalized)) {
+        return normalized;
+    }
+    return `arg_${normalized}`;
+}
+
+function serializeTranscriptArg(value: unknown): string | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return "[Unserializable]";
+    }
+}
+
+function buildTranscriptToolAttributes(
+    toolName: string,
+    args: unknown,
+    toolDef: AISdkTool | undefined
+): Record<string, string> | undefined {
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        if (toolName.startsWith("mcp_") && args !== undefined) {
+            const raw = truncateForTranscript(String(args), TRANSCRIPT_RAW_ARGS_MAX_LENGTH);
+            return { args: raw };
+        }
+        return undefined;
+    }
+
+    const argsObject = args as Record<string, unknown>;
+    const attrs: Record<string, string> = {};
+
+    const description = argsObject.description;
+    if (typeof description === "string" && description.trim().length > 0) {
+        attrs.description = description.trim();
+    }
+
+    const specs = toolDef?.transcriptArgsToInclude;
+    if (specs && specs.length > 0) {
+        for (const spec of specs) {
+            const raw = argsObject[spec.key];
+            const serialized = serializeTranscriptArg(raw);
+            if (!serialized || serialized.length === 0) {
+                continue;
+            }
+            const attrName = normalizeTranscriptAttrName(spec.attribute ?? spec.key);
+            attrs[attrName] = serialized;
+        }
+    } else if (toolName.startsWith("mcp_")) {
+        const rawArgs = truncateForTranscript(
+            JSON.stringify(argsObject),
+            TRANSCRIPT_RAW_ARGS_MAX_LENGTH
+        );
+        attrs.args = rawArgs;
+    }
+
+    return Object.keys(attrs).length > 0 ? attrs : undefined;
+}
+
+function setToolCallEventIdFromToolCallId(
+    conversationStore: FullRuntimeContext["conversationStore"],
+    toolCallId: string,
+    toolEventId: string
+): void {
+    const messages = conversationStore.getAllMessages();
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.messageType !== "tool-call" || !message.toolData) {
+            continue;
+        }
+        const hasToolCallId = (message.toolData as ToolCallPart[]).some(
+            (part) => part.toolCallId === toolCallId
+        );
+        if (!hasToolCallId) {
+            continue;
+        }
+        conversationStore.setEventId(i, toolEventId);
+        return;
+    }
+}
+
 /**
  * Configuration for setting up tool event handlers
  */
@@ -77,6 +177,15 @@ export function setupToolEventHandlers(config: ToolEventHandlersConfig): void {
             event.args
         );
 
+        // Generate human-readable summary from the tool's own formatter
+        const toolDef = toolsObject[event.toolName];
+        const humanReadable = toolDef?.getHumanReadableContent?.(event.args ?? {});
+        const transcriptToolAttributes = buildTranscriptToolAttributes(
+            event.toolName,
+            event.args,
+            toolDef
+        );
+
         conversationStore.addMessage({
             pubkey: context.agent.pubkey,
             ral: ralNumber,
@@ -90,6 +199,8 @@ export function setupToolEventHandlers(config: ToolEventHandlersConfig): void {
                     input: event.args ?? {},
                 },
             ] as ToolCallPart[],
+            ...(humanReadable ? { humanReadable } : {}),
+            ...(transcriptToolAttributes ? { transcriptToolAttributes } : {}),
         });
 
         const toolEvent = await toolTracker.trackExecution({
@@ -225,6 +336,7 @@ export function setupToolEventHandlers(config: ToolEventHandlersConfig): void {
 
         if (toolEventId) {
             conversationStore.setEventId(toolResultMessageIndex, toolEventId);
+            setToolCallEventIdFromToolCallId(conversationStore, event.toolCallId, toolEventId);
         }
 
         ralRegistry.setToolActive(

package/src/agents/role-categories.ts

@@ -0,0 +1,53 @@
+/**
+ * role-categories - Semantic classification for agents
+ *
+ * Agents have an optional `category` field for semantic classification and organizational purposes.
+ * Categories do NOT restrict tool access — all agents have access to all tools.
+ *
+ * Categories represent operational roles:
+ * - `principal`    — Human proxy (e.g., human-replica)
+ * - `orchestrator` — PMs, coordinators
+ * - `worker`       — Developers, implementers
+ * - `advisor`      — Experts, reviewers
+ * - `auditor`      — Testers, code reviewers
+ *
+ * Unknown/missing category remains undefined. Only set a category when explicitly known.
+ */
+
+/**
+ * Valid agent categories.
+ */
+export type AgentCategory = "principal" | "orchestrator" | "worker" | "advisor" | "auditor";
+
+
+/**
+ * All recognized category values for validation.
+ */
+export const VALID_CATEGORIES: readonly AgentCategory[] = [
+    "principal",
+    "orchestrator",
+    "worker",
+    "advisor",
+    "auditor",
+] as const;
+
+/**
+ * Check if a string is a valid agent category.
+ */
+export function isValidCategory(value: string): value is AgentCategory {
+    return VALID_CATEGORIES.includes(value as AgentCategory);
+}
+
+/**
+ * Resolve an agent's effective category.
+ * Returns the category if valid and provided, otherwise undefined.
+ *
+ * Categories are for semantic classification and organizational purposes only.
+ * They do not restrict tool access — all agents have access to all tools.
+ */
+export function resolveCategory(category: string | undefined): AgentCategory | undefined {
+    if (category && isValidCategory(category)) {
+        return category;
+    }
+    return undefined;
+}

package/src/agents/types/runtime.ts

@@ -2,6 +2,7 @@ import type { AgentMetadataStore } from "@/services/agents";
 import type { LLMService } from "@/llm/service";
 import type { MCPConfig, MCPServerConfig } from "@/llm/providers/types";
 import type { OnStreamStartCallback } from "@/llm/types";
+import type { AgentCategory } from "@/agents/role-categories";
 import type { NDKEvent, NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
 import type { Tool as CoreTool } from "ai";
 import type { AgentProjectConfig } from "./storage";
@@ -23,6 +24,12 @@ export interface AgentInstance {
     pubkey: string;
     signer: NDKPrivateKeySigner;
     role: string;
+    /**
+     * Agent category for semantic classification and organizational purposes.
+     * Resolved from the agent definition's category tag.
+     * No restrictions are applied based on category — all agents have access to all tools.
+     */
+    category?: AgentCategory;
     description?: string;
     instructions?: string;
     customInstructions?: string; // Custom system prompt instructions

package/src/agents/types/storage.ts

@@ -1,4 +1,5 @@
 import type { MCPServerConfig } from "@/llm/providers/types";
+import type { AgentCategory } from "@/agents/role-categories";
 
 /**
  * Default agent configuration block.
@@ -61,6 +62,12 @@ export interface ProjectScopedConfig {
 export interface StoredAgentData {
     name: string;
     role: string;
+    /**
+     * Agent category for role-based tool restrictions (TIP-01).
+     * Valid values: "principal", "orchestrator", "worker", "advisor", "auditor".
+     * When missing or unrecognized, defaults to "advisor" (most restrictive).
+     */
+    category?: AgentCategory;
     description?: string;
     instructions?: string;
     useCriteria?: string;

package/src/commands/agent/import/openclaw-distiller.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { llmServiceFactory } from "@/llm/LLMServiceFactory";
+import { logger } from "@/utils/logger";
 import type { LLMConfiguration } from "@/services/config/types";
 import type { OpenClawWorkspaceFiles } from "./openclaw-reader";
 
@@ -41,17 +42,72 @@ Given these workspace files, return a JSON object with exactly these fields:
 ${sections.join("\n\n")}`;
 }
 
+async function distillWithRetry<T>(
+    llmConfigs: LLMConfiguration[],
+    run: (service: ReturnType<typeof llmServiceFactory.createService>) => Promise<T>,
+): Promise<T> {
+    if (llmConfigs.length === 0) {
+        throw new Error("No LLM configurations available for distillation");
+    }
+
+    let lastError: unknown;
+    for (const config of llmConfigs) {
+        try {
+            const service = llmServiceFactory.createService(config);
+            return await run(service);
+        } catch (error) {
+            lastError = error;
+            if (llmConfigs.length > 1) {
+                logger.warn(
+                    `[distiller] call failed with ${config.provider}:${config.model}, trying next model...`
+                );
+            }
+        }
+    }
+
+    throw lastError;
+}
+
 export async function distillAgentIdentity(
     files: OpenClawWorkspaceFiles,
-    llmConfig: LLMConfiguration
+    llmConfigs: LLMConfiguration[]
 ): Promise<DistilledAgentIdentity> {
-    const service = llmServiceFactory.createService(llmConfig);
     const prompt = buildDistillationPrompt(files);
+    const messages = [{ role: "user" as const, content: prompt }];
+
+    return distillWithRetry(llmConfigs, async (service) => {
+        const { object } = await service.generateObject(messages, DistilledIdentitySchema);
+        return object;
+    });
+}
+
+export function buildUserContextPrompt(rawUserMd: string): string {
+    return `You are cleaning up a user profile document for use as context in an AI assistant's system prompt.
+
+Given the raw USER.md content below, produce a clean, concise summary of everything that would be useful for an AI assistant to know about this user. Write it as a brief markdown section.
+
+Keep anything that helps the assistant interact better: name, preferences, timezone, communication style, interests, projects, technical background, etc.
+
+Drop anything that is noise: unknown/empty fields, platform-specific metadata (IDs, timestamps of first conversations), internal bookkeeping, and formatting artifacts.
+
+If the document contains almost nothing useful, return an empty string.
+
+<USER.md>
+${rawUserMd}
+</USER.md>`;
+}
+
+export async function distillUserContext(
+    rawUserMd: string,
+    llmConfigs: LLMConfiguration[],
+): Promise<string> {
+    const prompt = buildUserContextPrompt(rawUserMd);
+    const messages = [{ role: "user" as const, content: prompt }];
 
-    const { object } = await service.generateObject(
-        [{ role: "user", content: prompt }],
-        DistilledIdentitySchema
-    );
+    const result = await distillWithRetry(llmConfigs, async (service) => {
+        const { text } = await service.generateText(messages);
+        return text;
+    });
 
-    return object;
+    return result.trim();
 }

package/src/commands/agent/import/openclaw-reader.ts

@@ -130,6 +130,60 @@ export async function readOpenClawAgents(stateDir: string): Promise<OpenClawAgen
     );
 }
 
+export interface OpenClawCredential {
+    provider: string;
+    apiKey: string;
+}
+
+/**
+ * Read provider credentials from OpenClaw's auth-profiles.json.
+ * Supports token, api_key, and oauth profile types.
+ * Returns deduplicated credentials (first occurrence per provider wins).
+ */
+export async function readOpenClawCredentials(stateDir: string): Promise<OpenClawCredential[]> {
+    const profilePath = path.join(stateDir, "agents", "main", "agent", "auth-profiles.json");
+    const content = await readFileOrNull(profilePath);
+    if (!content) return [];
+
+    let parsed: { profiles?: Record<string, Record<string, string>> };
+    try {
+        parsed = JSON.parse(content);
+    } catch {
+        return [];
+    }
+
+    if (!parsed.profiles) return [];
+
+    const credentials: OpenClawCredential[] = [];
+    const seenProviders = new Set<string>();
+
+    // Sort keys so `:default` profiles come first
+    const sortedKeys = Object.keys(parsed.profiles).sort((a, b) => {
+        const aDefault = a.includes(":default") ? 0 : 1;
+        const bDefault = b.includes(":default") ? 0 : 1;
+        return aDefault - bDefault || a.localeCompare(b);
+    });
+
+    for (const key of sortedKeys) {
+        const profile = parsed.profiles[key];
+        const provider = profile.provider;
+        if (!provider || seenProviders.has(provider)) continue;
+
+        const apiKey =
+            profile.type === "token" ? profile.token :
+            profile.type === "api_key" ? profile.key :
+            profile.type === "oauth" ? profile.access :
+            undefined;
+
+        if (apiKey) {
+            seenProviders.add(provider);
+            credentials.push({ provider, apiKey });
+        }
+    }
+
+    return credentials;
+}
+
 /**
  * Convert OpenClaw model format to TENEX format.
  * OpenClaw uses "provider/model", TENEX uses "provider:model".