@steerable/agent-ui 0.2.3 → 0.2.4

package/dist/state/useScrollLock.js

@@ -0,0 +1,74 @@
+/**
+ * `useScrollLock` — sticky-bottom scrolling for streaming message lists.
+ *
+ * The hook returns a callback ref to attach to the scroll container and a
+ * `scrollToBottom` imperative API. Behaviour:
+ *   - When the container's scroll position is within `threshold` px of the
+ *     bottom, the hook treats the user as "anchored" and re-runs
+ *     `scrollToBottom` whenever the dependency array `revalidateKeys` changes.
+ *   - As soon as the user scrolls up past `threshold`, the lock releases —
+ *     the list will no longer auto-scroll until the user scrolls back to the
+ *     bottom (or `scrollToBottom` is called explicitly, e.g. on send).
+ *
+ * Uses a callback ref so the listener attaches the moment the element mounts,
+ * not after a second effect pass. Matches deeppath's MessageList scroll
+ * handling minus the inline MutationObserver+IntersectionObserver soup.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+function maxScrollTop(el) {
+    return Math.max(0, el.scrollHeight - el.clientHeight);
+}
+export function useScrollLock(options = {}) {
+    const threshold = options.threshold ?? 24;
+    const elRef = useRef(null);
+    const cleanupRef = useRef(null);
+    const [isAnchored, setAnchored] = useState(true);
+    const anchoredRef = useRef(true);
+    anchoredRef.current = isAnchored;
+    const scrollToBottom = useCallback((behavior) => {
+        const el = elRef.current;
+        if (!el)
+            return;
+        el.scrollTo({
+            top: maxScrollTop(el),
+            behavior: behavior ?? options.behavior ?? 'auto',
+        });
+    }, [options.behavior]);
+    const setRef = useCallback((el) => {
+        if (cleanupRef.current) {
+            cleanupRef.current();
+            cleanupRef.current = null;
+        }
+        elRef.current = el;
+        if (!el)
+            return;
+        const handler = () => {
+            const distance = maxScrollTop(el) - el.scrollTop;
+            const anchored = distance <= threshold;
+            if (anchored !== anchoredRef.current) {
+                anchoredRef.current = anchored;
+                setAnchored(anchored);
+            }
+        };
+        el.addEventListener('scroll', handler, { passive: true });
+        cleanupRef.current = () => el.removeEventListener('scroll', handler);
+        // Run once to seed `isAnchored` from the current position.
+        handler();
+    }, [threshold]);
+    useEffect(() => {
+        return () => {
+            if (cleanupRef.current) {
+                cleanupRef.current();
+                cleanupRef.current = null;
+            }
+        };
+    }, []);
+    useEffect(() => {
+        if (anchoredRef.current)
+            scrollToBottom();
+        // Consumer-provided dependency array + the scroll callback.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, options.revalidateKeys ?? []);
+    return { setRef, isAnchored, scrollToBottom };
+}
+//# sourceMappingURL=useScrollLock.js.map

package/dist/state/useScrollLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollLock.js","sourceRoot":"","sources":["../../src/state/useScrollLock.ts"],"names":[],"mappings":"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"}

package/dist/state/useToolCallStream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `useToolCallStream` — turn the assistant message's `toolCalls` / `toolResult`
+ * (as maintained by `useChatStream`) into a derived `{ id -> {call, result,
+ * status, mode} }` map, so renderers can show per-call cards without
+ * threading status through the tree manually.
+ *
+ * Aggregates `useToolCallStatus` across all tool calls on a single message.
+ * Pure derivation, no I/O.
+ */
+import type { ChatMessage, ToolCall, ToolResult } from '@steerable/agent-protocol';
+import { type ToolCallMode, type ToolCallStatus } from '../hooks/useToolCallStatus.js';
+export interface ToolCallEntry {
+    call: ToolCall;
+    result?: ToolResult;
+    status: ToolCallStatus;
+    mode: ToolCallMode;
+    isDestructive: boolean;
+    requiresApproval: boolean;
+}
+export interface UseToolCallStreamOptions {
+    message: ChatMessage | null | undefined;
+    /**
+     * Optional per-call result lookup — when the runtime emits `tool_result`
+     * with a `callId`, we can pair it to the originating call rather than
+     * relying on `message.toolResult` (which always holds the last result).
+     */
+    resultByCallId?: Record<string, ToolResult>;
+    /** Optional mode override per tool name. */
+    modeByName?: Record<string, ToolCallMode>;
+}
+export interface UseToolCallStreamReturn {
+    entries: ToolCallEntry[];
+    pendingCount: number;
+    errorCount: number;
+}
+export declare function useToolCallStream(options: UseToolCallStreamOptions): UseToolCallStreamReturn;
+export { useToolCallStatus } from '../hooks/useToolCallStatus.js';
+//# sourceMappingURL=useToolCallStream.d.ts.map

package/dist/state/useToolCallStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolCallStream.d.ts","sourceRoot":"","sources":["../../src/state/useToolCallStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC5C,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CA8BzB;AAgCD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/state/useToolCallStream.js

@@ -0,0 +1,74 @@
+/**
+ * `useToolCallStream` — turn the assistant message's `toolCalls` / `toolResult`
+ * (as maintained by `useChatStream`) into a derived `{ id -> {call, result,
+ * status, mode} }` map, so renderers can show per-call cards without
+ * threading status through the tree manually.
+ *
+ * Aggregates `useToolCallStatus` across all tool calls on a single message.
+ * Pure derivation, no I/O.
+ */
+import { useMemo } from 'react';
+export function useToolCallStream(options) {
+    const message = options.message ?? null;
+    return useMemo(() => {
+        if (!message || !Array.isArray(message.toolCalls)) {
+            return { entries: [], pendingCount: 0, errorCount: 0 };
+        }
+        const entries = message.toolCalls.map((call) => {
+            const lookup = options.resultByCallId?.[call.id];
+            const fallback = message.toolResult && message.toolResult.callId === call.id
+                ? message.toolResult
+                : undefined;
+            const result = lookup ?? fallback ?? message.toolResult;
+            const status = deriveStatus(result);
+            const mode = options.modeByName?.[call.name] ?? inferMode(call.name);
+            return {
+                call,
+                result,
+                status,
+                mode,
+                isDestructive: mode === 'destructive',
+                requiresApproval: mode === 'local',
+            };
+        });
+        return {
+            entries,
+            pendingCount: entries.filter((e) => e.status === 'pending').length,
+            errorCount: entries.filter((e) => e.status === 'error').length,
+        };
+    }, [message, options.resultByCallId, options.modeByName]);
+}
+// `useToolCallStatus` is per-call; this hook is the bulk variant. We keep the
+// inference rules in sync by re-using the same heuristics here.
+const READ_PATTERNS = [/^get[_-]/, /^list[_-]/, /^read[_-]/, /^search[_-]/];
+const DESTRUCTIVE_PATTERNS = [
+    /^delete[_-]/,
+    /^remove[_-]/,
+    /^archive[_-]/,
+    /^purge[_-]/,
+    /^drop[_-]/,
+];
+const SAFE_WRITE_PATTERNS = [/^create[_-]/, /^update[_-]/, /^add[_-]/, /^set[_-]/];
+const LOCAL_PATTERNS = [/^local[_-]/, /^shell[_-]/, /^exec[_-]/];
+function inferMode(name) {
+    const lower = name.toLowerCase();
+    if (READ_PATTERNS.some((re) => re.test(lower)))
+        return 'read';
+    if (LOCAL_PATTERNS.some((re) => re.test(lower)))
+        return 'local';
+    if (DESTRUCTIVE_PATTERNS.some((re) => re.test(lower)))
+        return 'destructive';
+    if (SAFE_WRITE_PATTERNS.some((re) => re.test(lower)))
+        return 'safe_write';
+    return 'unknown';
+}
+function deriveStatus(result) {
+    if (!result)
+        return 'pending';
+    if (result.success === false)
+        return 'error';
+    return 'done';
+}
+// Re-export the per-call hook for convenience.
+export { useToolCallStatus } from '../hooks/useToolCallStatus.js';
+//# sourceMappingURL=useToolCallStream.js.map

package/dist/state/useToolCallStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolCallStream.js","sourceRoot":"","sources":["../../src/state/useToolCallStream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-ui",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Steerable framework Tier 4 — headless React hooks (useAgentSession, useChatStream, useToolCallStatus) and Tailwind-themed components (ChatPanel, MessageList, OrchestrationPlanCard, ToolCallRenderer, SSEStreamView) for embedding Steerable agents in any React app.",
   "license": "Apache-2.0",
   "homepage": "https://pathlyapp.github.io/steerable-framework/storybook/",
@@ -41,6 +41,14 @@
     "./components": {
       "types": "./dist/components/index.d.ts",
       "import": "./dist/components/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./cards": {
+      "types": "./dist/cards/index.d.ts",
+      "import": "./dist/cards/index.js"
     }
   },
   "files": [
@@ -49,7 +57,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@steerable/agent-protocol": "0.2.3"
+    "@steerable/agent-protocol": "0.2.4"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/src/cards/ActionSegmentCard.tsx

@@ -0,0 +1,60 @@
+/**
+ * `<ActionSegmentCard />`
+ *
+ * Horizontal strip of inline tool / action invocations within a single
+ * assistant message. Each segment is rendered with `<ToolExecutionCard />` so
+ * the visual behaviour matches the standalone tool-execution card.
+ */
+import * as React from 'react';
+import type { ActionSegmentPayload, ToolExecutionPayload } from '@steerable/agent-protocol';
+import { ToolExecutionCard } from './ToolExecutionCard.js';
+
+export interface ActionSegmentCardProps {
+  payload: ActionSegmentPayload;
+  className?: string;
+  renderArgs?: (args: unknown) => React.ReactNode;
+  renderOutput?: (output: unknown) => React.ReactNode;
+}
+
+function segmentToTool(segment: ActionSegmentPayload['segments'][number]): ToolExecutionPayload {
+  return {
+    id: segment.id,
+    name: segment.kind,
+    status: segment.status,
+    summary: segment.label ?? null,
+    args: segment.args,
+    output: segment.output,
+    error: segment.error ?? null,
+    durationMs:
+      segment.startedAt && segment.finishedAt
+        ? Math.max(0, Date.parse(segment.finishedAt) - Date.parse(segment.startedAt))
+        : null,
+    icon: null,
+    expandable: true,
+  };
+}
+
+export const ActionSegmentCard: React.FC<ActionSegmentCardProps> = ({
+  payload,
+  className,
+  renderArgs,
+  renderOutput,
+}) => {
+  const segments = payload.segments ?? [];
+  if (segments.length === 0) return null;
+
+  return (
+    <div className={['steerable-action-segment space-y-1.5', className].filter(Boolean).join(' ')}>
+      {segments.map((s) => (
+        <ToolExecutionCard
+          key={s.id}
+          payload={segmentToTool(s)}
+          renderArgs={renderArgs}
+          renderOutput={renderOutput}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default ActionSegmentCard;

package/src/cards/AnalysisDocumentCard.tsx

@@ -0,0 +1,81 @@
+/**
+ * `<AnalysisDocumentCard />`
+ *
+ * Long-form markdown document card.
+ *
+ * The framework deliberately does not pull in `react-markdown` / `remark-gfm` /
+ * `github-markdown-css` -- the consumer must pass a `renderMarkdown` slot (or
+ * a `Markdown` child) to do the actual rendering. Default fallback is a `<pre>`
+ * block.
+ *
+ * Header variants:
+ *  - `inline` (default): title sits inline with the document icon.
+ *  - `strip`: title becomes a `bg-muted/50` strip on top, with the icon hidden.
+ *
+ * Footer slot lets host apps attach an actions bar (deeppath uses this for
+ * "转化为行动 / 保存到笔记 / 保存为 PDF / 深入研究 / 复制 / 模型 + 时间").
+ */
+import * as React from 'react';
+import type { AnalysisDocumentPayload } from '@steerable/agent-protocol';
+import { BookIcon } from './icons.js';
+import { asReactNode, type RenderSlotResult } from './types.js';
+
+export type AnalysisDocumentHeaderVariant = 'inline' | 'strip';
+
+export interface AnalysisDocumentCardProps {
+  payload: AnalysisDocumentPayload;
+  isComplete?: boolean;
+  renderMarkdown?: (body: string) => RenderSlotResult;
+  renderFooter?: () => RenderSlotResult;
+  className?: string;
+  bodyClassName?: string;
+  headerVariant?: AnalysisDocumentHeaderVariant;
+}
+
+export const AnalysisDocumentCard: React.FC<AnalysisDocumentCardProps> = ({
+  payload,
+  renderMarkdown,
+  renderFooter,
+  className,
+  bodyClassName,
+  headerVariant = 'inline',
+}) => {
+  return (
+    <article
+      className={[
+        'steerable-analysis-document overflow-hidden rounded-lg border border-[var(--agent-border,#e5e7eb)] bg-[var(--agent-card-bg,#fff)] text-sm text-[var(--agent-foreground,#111827)]',
+        className,
+      ].filter(Boolean).join(' ')}
+    >
+      {payload.title && headerVariant === 'strip' ? (
+        <div className="border-b border-[var(--agent-border,#e5e7eb)] bg-[var(--agent-muted,#f3f4f6)]/50 px-4 py-2">
+          <span className="block truncate text-xs font-medium text-[var(--agent-muted-foreground,#6b7280)]">
+            {payload.title}
+          </span>
+        </div>
+      ) : (
+        <header className="mb-3 flex items-center gap-2 border-b border-[var(--agent-border,#e5e7eb)] px-4 pt-3 pb-2">
+          <BookIcon size={14} className="text-[var(--agent-muted-foreground,#6b7280)]" />
+          <h3 className="text-sm font-medium">{payload.title || '分析报告'}</h3>
+          {payload.modelId && (
+            <span className="ml-auto rounded-full bg-[var(--agent-muted,#f3f4f6)] px-2 py-0.5 text-[10px] uppercase tracking-wider text-[var(--agent-muted-foreground,#6b7280)]">
+              {payload.modelId}
+            </span>
+          )}
+        </header>
+      )}
+
+      <div className={['p-4', bodyClassName].filter(Boolean).join(' ')}>
+        {renderMarkdown ? (
+          asReactNode(renderMarkdown(payload.body))
+        ) : (
+          <pre className="whitespace-pre-wrap break-words font-sans">{payload.body}</pre>
+        )}
+      </div>
+
+      {renderFooter && asReactNode(renderFooter())}
+    </article>
+  );
+};
+
+export default AnalysisDocumentCard;