@qilin-agent/client-ui-sidebar-tasks 0.0.0-stage → 3.1.4

package/lib/types/client/tasks-graph-layout.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure layered layout for the tasks graph: depth rows, leaf-packed horizontal
+ * ordering (parents centered over their subtrees), cubic parent→child edges,
+ * and the content bounding box the canvas fits to.
+ *
+ * Folded and unhydrated groups arrive as leaf nodes (aggregate and placeholder
+ * kinds) — the view model has already applied the expansion state before this
+ * runs. Framework-free: every function is a pure mapping from the view model
+ * to rectangles.
+ */
+import type { TaskNodeVM, TasksGraphModel } from './tasks-graph-model.ts';
+/** Node card metrics in px at zoom 1: the card is a top segment plus a bottom bar. */
+export declare const TASK_NODE_W = 208;
+/** Height of the card's top segment (badge line plus label line). */
+export declare const TASK_NODE_TOP_H = 46;
+/** Height of the card's bottom status bar. */
+export declare const TASK_NODE_BAR_H = 20;
+/** Total card height. */
+export declare const TASK_NODE_H: number;
+/**
+ * Arrangement modes (the arrange control):
+ *
+ * - `tree` — the hierarchical default, parents centered over their subtrees;
+ * - `compact` — the same hierarchy with tighter gaps, for deep trees on a
+ *   narrow pane;
+ * - `grid` — depth rows packed into a column grid, wrapping after
+ *   {@link GRID_MAX_COLS}, which keeps a wide fan-out readable.
+ */
+export type TaskLayoutMode = 'tree' | 'compact' | 'grid';
+/** Grid mode wraps a depth row after this many columns. */
+export declare const GRID_MAX_COLS = 6;
+/** One laid-out node: the view-model node plus its canvas rectangle. */
+export interface TaskNodeBox {
+    readonly node: TaskNodeVM;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** One laid-out edge: parent bottom-center → child top-center, as a cubic curve. */
+export interface TaskEdgePath {
+    /** `${from}->${to}`; also the SVG element key. */
+    readonly id: string;
+    /** The SVG path data. */
+    readonly d: string;
+    /** The child node id. */
+    readonly to: string;
+}
+/** One manual position delta for one node (what a drag writes). */
+export interface NodeOffset {
+    readonly x: number;
+    readonly y: number;
+}
+/** Manual node offsets by node id, relative to the auto layout. */
+export type NodeOffsets = Readonly<Record<string, NodeOffset>>;
+/** The laid-out graph: node boxes, edge paths, and the content bounding box. */
+export interface TasksGraphLayout {
+    readonly nodes: readonly TaskNodeBox[];
+    readonly edges: readonly TaskEdgePath[];
+    /** Content box size; a dragged node can push it beyond the auto layout. */
+    readonly width: number;
+    readonly height: number;
+    /** Content box origin; negative once a node is dragged up or left of 0,0. */
+    readonly minX: number;
+    readonly minY: number;
+}
+/**
+ * Lay out the view model.
+ * @param model - the view model (pre-order nodes plus the children index).
+ * @param offsets - manual node offsets applied after auto placement.
+ * @param mode - the arrangement mode.
+ * @returns node boxes, edge paths, and the content box.
+ */
+export declare function layoutTasksGraph(model: TasksGraphModel, offsets?: NodeOffsets, mode?: TaskLayoutMode): TasksGraphLayout;
+/**
+ * Every id in one node's subtree, the node itself first.
+ * @param model - the view model, for the children graph.
+ * @param nodeId - the subtree root.
+ * @returns the subtree ids in depth-first order.
+ */
+export declare function subtreeIds(model: Pick<TasksGraphModel, 'childrenOf'>, nodeId: string): string[];
+/**
+ * The offsets after dragging one node by (dx, dy).
+ *
+ * Always computed from the offsets captured when the gesture started plus the
+ * total delta, so a long drag cannot accumulate rounding drift. With
+ * `subtree` the descendants ride along — the default, since a card that owns
+ * other cards moves them naturally; the Alt key drags the single card.
+ * @param model - the view model, for the children graph.
+ * @param base - the offsets captured at gesture start.
+ * @param nodeId - the dragged node.
+ * @param dx - the total horizontal delta.
+ * @param dy - the total vertical delta.
+ * @param subtree - whether the node's descendants move too.
+ * @returns the next offsets.
+ */
+export declare function dragOffsets(model: Pick<TasksGraphModel, 'childrenOf'>, base: NodeOffsets, nodeId: string, dx: number, dy: number, subtree: boolean): NodeOffsets;
+/**
+ * Whether any manual offset is in effect; drives the reset affordance.
+ * @param offsets - the offsets in force.
+ * @returns whether at least one node is displaced.
+ */
+export declare function hasOffsets(offsets: NodeOffsets): boolean;
+//# sourceMappingURL=tasks-graph-layout.d.ts.map

package/lib/types/client/tasks-graph-model.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The tasks graph's shared view model: the single source the canvas renders.
+ *
+ * Inactive direct children split into two groups by their continuation mode —
+ * `done` (one-shot, finished) and `standby` (continuable, finished a turn and
+ * callable again). A group at or over {@link FOLD_MIN} renders as one
+ * aggregate node until the user expands it, so a long-finished fan-out stays
+ * one card instead of dozens. A child whose own catalog has not been read
+ * contributes one placeholder node standing in for its unread level. Workflow
+ * runs hang under the agent that started them, their members re-parented
+ * below the run's phase boxes.
+ *
+ * Labels and secondaries are injected (`labelOf` / `secondaryOf`) so this
+ * module stays free of the locale runtime. Pure over its inputs.
+ */
+import type { SessionId } from '@qilin-agent/session/types';
+import type { SubagentAddress } from '@qilin-agent/subagent/client';
+import type { CatalogRow, Catalogs } from './rows.ts';
+/** Fold threshold: a done or standby group at or over this size renders as one aggregate node. */
+export declare const FOLD_MIN = 6;
+/** Discriminates what a graph node renders as. */
+export type TaskNodeKind = 'main' | 'subagent' | 'done-agg' | 'standby-agg' | 'placeholder' | 'diagnostic'
+/** One workflow run, hung under the agent that started it. */
+ | 'run'
+/** One phase box of a run (members grouped per phase). */
+ | 'phase'
+/** A run member without a catalog row, synthesized from the run's own data. */
+ | 'member';
+/** One session row the model reads. The Session list's summaries satisfy this structurally. */
+export interface GraphSummaryEntry {
+    readonly id: SessionId;
+    /** The human-facing label the session is known by. */
+    readonly displayTitle: string;
+    readonly running: boolean;
+    readonly parentId?: SessionId;
+    readonly origin?: 'subagent';
+}
+/** One member of a workflow run phase. */
+export interface WorkflowRunMemberRow {
+    readonly seq: number;
+    readonly label: string;
+    readonly childId: SessionId;
+    /** The member's settled outcome; absent while it still runs. */
+    readonly outcome?: string;
+}
+/** One phase group of a workflow run. */
+export interface WorkflowRunPhaseRow {
+    /** The phase name; absent for members the run never phased. */
+    readonly phase?: string;
+    readonly members: readonly WorkflowRunMemberRow[];
+}
+/** One workflow run, as the model hangs it under its origin agent. */
+export interface WorkflowRunRow {
+    readonly runId: string;
+    readonly name: string;
+    /** The Session the run was started from; its node hangs under that agent. */
+    readonly originSessionId: SessionId;
+    readonly running: boolean;
+    readonly phases: readonly WorkflowRunPhaseRow[];
+}
+/** One renderable node of the tasks graph. */
+export interface TaskNodeVM {
+    /** A Session id, a synthesized key (`done:${id}` / `standby:${id}` / `run:` / `phase:` / `placeholder:`), or a member's Session id. */
+    readonly id: string;
+    readonly kind: TaskNodeKind;
+    /** The parent id; `undefined` for the root. */
+    readonly parentId: string | undefined;
+    /** Nesting level under the root. */
+    readonly depth: number;
+    readonly label: string;
+    readonly secondary: string;
+    readonly running: boolean;
+    /** Whether the node is the Session the page is currently drawing. */
+    readonly current: boolean;
+    /** Subagent nodes only: the address every navigation travels through. */
+    readonly address: SubagentAddress | undefined;
+    /** How many members a placeholder or aggregate node stands in for. */
+    readonly childCount: number | undefined;
+    /** Aggregate nodes only: the key that toggles them in the fold state. */
+    readonly aggregateKey: string | undefined;
+}
+/** The built view model: flat pre-order nodes plus the parent→children index. */
+export interface TasksGraphModel {
+    /** Pre-order: every parent before its children. */
+    readonly nodes: readonly TaskNodeVM[];
+    /** Visible children per parent id (the root id included). */
+    readonly childrenOf: Readonly<Record<string, readonly TaskNodeVM[]>>;
+}
+/** The model's inputs. */
+export interface BuildTasksGraphModelInput {
+    /** The Session the page draws; the graph's root and main node. */
+    readonly rootId: SessionId;
+    /** Direct-child catalogs keyed by parent Session id. */
+    readonly catalogs: Catalogs;
+    /** Session summaries keyed by id (labels, running state, lineage counts). */
+    readonly summaries: Readonly<Record<SessionId, GraphSummaryEntry>>;
+    /** Aggregate keys currently expanded; the default state is folded. */
+    readonly expanded: ReadonlySet<string>;
+    /** The Session the page highlights as current. */
+    readonly currentSessionId: SessionId;
+    /** Workflow runs, each hung under its origin agent; absent means none. */
+    readonly runs?: readonly WorkflowRunRow[];
+    /**
+     * The display label of one catalog child.
+     * @param entry - the catalog's child row.
+     * @param summary - the child's summary, when the Session list holds one.
+     * @returns the label the node shows.
+     */
+    readonly labelOf: (entry: Extract<CatalogRow, {
+        kind: 'child';
+    }>, summary: GraphSummaryEntry | undefined) => string;
+    /**
+     * The secondary line of one catalog child.
+     * @param entry - the catalog's child row.
+     * @returns the secondary the node shows.
+     */
+    readonly secondaryOf: (entry: Extract<CatalogRow, {
+        kind: 'child';
+    }>) => string;
+}
+/**
+ * Build the tasks graph view model.
+ *
+ * A level is one parent's catalog, siblings in catalog order, and the walk
+ * descends only into a child whose own catalog has settled; a child the page
+ * has never read contributes one placeholder. The seen set makes a repeated
+ * or cyclic catalog an ordinary skip rather than an endless walk.
+ * @param input - the model's inputs.
+ * @returns pre-order nodes and the parent→children index.
+ */
+export declare function buildTasksGraphModel(input: BuildTasksGraphModelInput): TasksGraphModel;
+//# sourceMappingURL=tasks-graph-model.d.ts.map

package/lib/types/client/tasks-graph-store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The tasks page's graph view state: which form the subagents section draws,
+ * which aggregate groups the user expanded, and the canvas's arrangement,
+ * manual node offsets, and camera — the state that survives the body's
+ * unmounts. One bucket per store instance; the registration is session-scoped,
+ * so a tree's framing comes back with its Session.
+ */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { NodeOffsets, TaskLayoutMode } from './tasks-graph-layout.ts';
+/** Which form the subagents section draws. */
+export type TasksGraphViewKind = 'list' | 'graph';
+/** The canvas camera: zoom, translate, and whether the user took it over. */
+export interface TasksGraphCamera {
+    readonly k: number;
+    readonly tx: number;
+    readonly ty: number;
+    /**
+     * The user panned or zoomed: the auto-fit policy stops steering the canvas
+     * until an arrange resets the framing.
+     */
+    readonly userAdjusted: boolean;
+}
+/** The graph view's state. */
+export interface TasksGraphState {
+    /** Which form the subagents section draws; the list stays the default. */
+    view: TasksGraphViewKind;
+    /** Aggregate keys the user expanded, keyed `done-agg:${id}` / `standby-agg:${id}`. */
+    expanded: Record<string, boolean>;
+    /** The canvas arrangement. */
+    mode: TaskLayoutMode;
+    /** Manual node offsets from drags, relative to the auto layout. */
+    offsets: NodeOffsets;
+    /** The canvas camera; `undefined` until the first fit. */
+    camera: TasksGraphCamera | undefined;
+}
+/** The store's write set. */
+type TasksGraphActions = {
+    /**
+     * Switch the subagents section's form.
+     * @param d - draft state.
+     * @param view - the form to show.
+     */
+    viewSet: (d: TasksGraphState, view: TasksGraphViewKind) => void;
+    /**
+     * Expand or collapse one aggregate group.
+     * @param d - draft state.
+     * @param key - the aggregate's fold key.
+     */
+    aggregateToggled: (d: TasksGraphState, key: string) => void;
+    /**
+     * Rearrange the canvas: the new mode clears the manual offsets and the
+     * camera, so the next auto-fit frames the fresh arrangement.
+     * @param d - draft state.
+     * @param mode - the arrangement to apply.
+     */
+    modeArranged: (d: TasksGraphState, mode: TaskLayoutMode) => void;
+    /**
+     * Record one node drag's offsets, replacing the previous gesture frame.
+     * @param d - draft state.
+     * @param offsets - the offsets in force after this frame.
+     */
+    offsetsDragged: (d: TasksGraphState, offsets: NodeOffsets) => void;
+    /**
+     * Drop every manual offset; every node returns to its auto-layout spot.
+     * @param d - draft state.
+     */
+    offsetsReset: (d: TasksGraphState) => void;
+    /**
+     * Move the canvas camera. A frame identical to the one in force writes
+     * nothing, so a settled auto-fit cannot loop re-publishing itself.
+     * @param d - draft state.
+     * @param camera - the camera to put in force.
+     */
+    cameraMoved: (d: TasksGraphState, camera: TasksGraphCamera) => void;
+};
+/**
+ * Declare the graph view's store.
+ * @returns the store handle the registration declares.
+ */
+export declare function createTasksGraphStore(): EngineStoreHandle<TasksGraphState, TasksGraphActions>;
+export {};
+//# sourceMappingURL=tasks-graph-store.d.ts.map

package/lib/types/client/work-sources.d.ts

@@ -0,0 +1,25 @@
+import type { SessionListState } from '@qilin-agent/api-session-controller/client';
+import type { JobView } from '@qilin-agent/jobs/view';
+import type { UseSessions } from '@qilin-agent/client-ui-session/client';
+import type { InjectFace } from '@qilin-agent/client-ui-slots';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { TasksJobsFace } from './face.ts';
+import { catalogsOf } from './rows.ts';
+/** The seats the hook reads: the standing Session list and the injected jobs roster. */
+type WorkSeats = Pick<InjectFace<TasksJobsFace>, 'useJobs' | 'watchRows'> & {
+    readonly useSessions: UseSessions;
+};
+/**
+ * Read the Session list and the job roster once per render and derive the
+ * running-work catalogs from them.
+ * @param sessionId - the Session whose job rows and subagent topology to read.
+ * @param seats - the standing Session list, the bound jobs roster, and its watcher.
+ * @returns this Session's job rows, the Session list summaries the surfaces fold over, and the running catalogs keyed by Session.
+ */
+export declare function useWorkSources(sessionId: SessionId, seats: WorkSeats): {
+    readonly jobs: readonly JobView[];
+    readonly summaries: SessionListState['byId'];
+    readonly catalogs: ReturnType<typeof catalogsOf>;
+};
+export {};
+//# sourceMappingURL=work-sources.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Pure host half; the whole tab type lives in the browser export. */
+/** Host plugin body: the tasks page contributes nothing to the host tree. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@qilin-agent/client-ui-sidebar-tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Subagent topology and background-job tab type for the right Sidebar: this Session's direct-child catalog, the descendant totals its summary lineage records, and its live job list",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-sidebar-tasks"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-session-controller",
+        "@qilin-agent/client-ui-primitives",
+        "@qilin-agent/client-ui-session",
+        "@qilin-agent/client-ui-sidebar-right"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@qilin-agent/jobs": "3.1.4",
+    "@qilin-agent/api-remotes": "3.1.4",
+    "@qilin-agent/client-locale": "3.1.4",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/api-session-controller": "3.1.4",
+    "@qilin-agent/api-job-controller": "3.1.4",
+    "@qilin-agent/client-test-runtime": "3.1.4",
+    "@qilin-agent/client-ui-primitives": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-ui-session": "3.1.4",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.4",
+    "@qilin-agent/client-ui-slots": "3.1.4",
+    "@qilin-agent/client-ui-workspace": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/subagent": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/typert-protocol": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }