@lssm/lib.contracts-spec 17.3.2

package/dist/agent/commands/graphOps.command.d.ts

@@ -0,0 +1,198 @@
+/**
+ * graphOps — 4 LLM-facing graph operation commands (M3 P7/W7.1).
+ *
+ * Implements the AI cost-ceiling spec from `m3-p0-ai-cost-ceiling.md`.
+ * Each command carries per-tool token budgets exported as `GRAPH_AI_BUDGETS`.
+ *
+ * Commands:
+ *  - `graph.search`  — NL query → ranked node/edge IDs + viewport suggestion
+ *  - `graph.filter`  — NL query → GraphFilterSpec for the filter rack
+ *  - `graph.cluster` — NL query → cluster groupings + labels
+ *  - `graph.suggest` — NL query → ranked graph-edit suggestions (read-only)
+ *
+ * All commands require `auth: 'user'` and emit `ai.graph.query` observability
+ * events via `@lssm/lib.observability`.
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+export interface GraphAiBudget {
+    /** Maximum input tokens per invocation. */
+    readonly maxInputTokens: number;
+    /** Maximum output tokens per invocation. */
+    readonly maxOutputTokens: number;
+    /** Hard USD cap per invocation (Anthropic Sonnet-4 reference pricing). */
+    readonly hardCapUsd: number;
+}
+/**
+ * Per-tool token + cost budgets.
+ *
+ * Enforcement is applied at the `@lssm/lib.ai-agent` layer.
+ * Per-session ceiling: $0.50 / 50 queries. Per-app ceiling: $5/user/day.
+ *
+ * Reference: `m3-p0-ai-cost-ceiling.md`
+ */
+export declare const GRAPH_AI_BUDGETS: {
+    readonly 'graph.search': {
+        readonly maxInputTokens: 1000;
+        readonly maxOutputTokens: 200;
+        readonly hardCapUsd: 0.005;
+    };
+    readonly 'graph.filter': {
+        readonly maxInputTokens: 1200;
+        readonly maxOutputTokens: 300;
+        readonly hardCapUsd: 0.008;
+    };
+    readonly 'graph.cluster': {
+        readonly maxInputTokens: 1500;
+        readonly maxOutputTokens: 400;
+        readonly hardCapUsd: 0.011;
+    };
+    readonly 'graph.suggest': {
+        readonly maxInputTokens: 2000;
+        readonly maxOutputTokens: 800;
+        readonly hardCapUsd: 0.02;
+    };
+};
+export declare const GraphSearchDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphSearchCommand: import("../..").OperationSpec<SchemaModel<{
+    query: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    nodeIds: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    edgeIds: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /** `{ centerX, centerY, zoom }` viewport suggestion, or absent. */
+    viewportSuggestion: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: true;
+    };
+}>, undefined>;
+export declare const GraphFilterDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphFilterCommand: import("../..").OperationSpec<SchemaModel<{
+    query: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    /** Serialised `GraphFilterSpec` JSON. */
+    filter: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /** Human-readable description of the resulting filter. */
+    description: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, undefined>;
+export declare const GraphClusterDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphClusterCommand: import("../..").OperationSpec<SchemaModel<{
+    query: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Max number of clusters to generate. Defaults to 8. */
+    maxClusters: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    /**
+     * Array of `{ id, label, nodeIds, color? }` cluster descriptors.
+     * Serialised as JSONObject due to nested array shape.
+     */
+    clusters: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /** Human-readable explanation of the clustering strategy applied. */
+    rationale: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, undefined>;
+export declare const GraphSuggestDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphSuggestCommand: import("../..").OperationSpec<SchemaModel<{
+    query: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Max number of suggestions to return. Defaults to 5. */
+    maxSuggestions: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    /**
+     * Ranked array of `{ id, label, description, confidence, action }` suggestions.
+     * `action` is a human-readable description of the proposed edit.
+     * Read-only — mutations are never applied without explicit user confirmation.
+     */
+    suggestions: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /** Whether the response was truncated by the token budget. */
+    truncated: {
+        type: import("@lssm/lib.schema").FieldType<boolean, boolean>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/agent/commands/graphOps.command.js

@@ -0,0 +1,31 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as a}from"../../docs/registry.js";import{defineCommand as r}from"../../operations/index.js";import{AGENT_DOMAIN as s,AGENT_OWNERS as n,AGENT_STABILITY as o,AGENT_TAGS as u}from"../constants.js";export const GRAPH_AI_BUDGETS={"graph.search":{maxInputTokens:1000,maxOutputTokens:200,hardCapUsd:0.005},"graph.filter":{maxInputTokens:1200,maxOutputTokens:300,hardCapUsd:0.008},"graph.cluster":{maxInputTokens:1500,maxOutputTokens:400,hardCapUsd:0.011},"graph.suggest":{maxInputTokens:2000,maxOutputTokens:800,hardCapUsd:0.02}};const i=[...u,"graph","ai","nlq","m3"];const p=new t({name:"GraphSearchInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1}}});const c=new t({name:"GraphSearchOutput",fields:{nodeIds:{type:e.JSONObject(),isOptional:!1},edgeIds:{type:e.JSONObject(),isOptional:!1},viewportSuggestion:{type:e.JSONObject(),isOptional:!0}}});export const GraphSearchDocBlock={id:"docs.tech.graph.search",title:"graph.search \u2014 NL node search",summary:"Natural-language graph search returning ranked node/edge IDs and an optional viewport suggestion. Budget: 1 000 in / 200 out / $0.005.",kind:"reference",visibility:"public",route:"/docs/tech/graph/search",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:"# graph.search\n\nTranslates a natural-language query into ranked `nodeIds` and `edgeIds`.\nAlso returns an optional viewport suggestion `{ centerX, centerY, zoom }`\nthe canvas can animate to.\n\n## Budget (`m3-p0-ai-cost-ceiling.md`)\nmaxInputTokens=1 000 \xB7 maxOutputTokens=200 \xB7 hardCapUsd=$0.005"};export const GraphSearchCommand=r({meta:{key:"graph.search",title:"Graph search",version:"1.0.0",description:"Natural-language graph search returning ranked node/edge IDs.",goal:"Let users find graph nodes and edges via plain-English queries.",context:["AI-powered search over the current graph context.","Budget: maxInputTokens=1000, maxOutputTokens=200, hardCapUsd=$0.005.","Emits ai.graph.query observability event on every invocation.","Cost enforcement at @lssm/lib.ai-agent layer."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.search")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:p,output:c,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The NL query could not be interpreted.",http:422,when:"Query is empty, too ambiguous, or refers to non-existent context."}}},policy:{auth:"user"}});const l=new t({name:"GraphFilterInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1}}});const d=new t({name:"GraphFilterOutput",fields:{filter:{type:e.JSONObject(),isOptional:!1},description:{type:e.String_unsecure(),isOptional:!1}}});export const GraphFilterDocBlock={id:"docs.tech.graph.filter",title:"graph.filter \u2014 NL filter generation",summary:"Translates a NL query into a GraphFilterSpec for the filter rack. Budget: 1 200 in / 300 out / $0.008.",kind:"reference",visibility:"public",route:"/docs/tech/graph/filter",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.filter
+
+Translates a natural-language filter request into a \`GraphFilterSpec\`
+JSON that the filter rack can apply directly.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 200 \xB7 maxOutputTokens=300 \xB7 hardCapUsd=$0.008`};export const GraphFilterCommand=r({meta:{key:"graph.filter",title:"Graph filter",version:"1.0.0",description:"NL query to GraphFilterSpec for the filter rack.",goal:"Let users create graph filters via plain-English queries.",context:["Outputs a serialised GraphFilterSpec usable by the filter rack and FacetPanel.","Budget: maxInputTokens=1200, maxOutputTokens=300, hardCapUsd=$0.008.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.filter")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:l,output:d,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The NL query could not be converted to a valid filter.",http:422,when:"Query is too ambiguous or refers to unknown field names."}}},policy:{auth:"user"}});const g=new t({name:"GraphClusterInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1},maxClusters:{type:e.Int_unsecure(),isOptional:!0}}});const h=new t({name:"GraphClusterOutput",fields:{clusters:{type:e.JSONObject(),isOptional:!1},rationale:{type:e.String_unsecure(),isOptional:!1}}});export const GraphClusterDocBlock={id:"docs.tech.graph.cluster",title:"graph.cluster \u2014 NL cluster grouping",summary:"Generates cluster groupings with labels from a NL strategy query. Budget: 1 500 in / 400 out / $0.011.",kind:"reference",visibility:"public",route:"/docs/tech/graph/cluster",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.cluster
+
+Groups graph nodes into labelled clusters based on a natural-language
+clustering strategy (e.g., "group by team ownership", "cluster by data flow").
+
+## Output shape
+\`clusters: Array<{ id, label, nodeIds, color? }>\`
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 500 \xB7 maxOutputTokens=400 \xB7 hardCapUsd=$0.011`};export const GraphClusterCommand=r({meta:{key:"graph.cluster",title:"Graph cluster",version:"1.0.0",description:"NL strategy query to cluster groupings with labels.",goal:"Let users group graph nodes into meaningful clusters via plain-English.",context:["Complements the useGraphCluster hook (W4.6). Outputs cluster descriptors","that the hook can apply directly.","Budget: maxInputTokens=1500, maxOutputTokens=400, hardCapUsd=$0.011.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.cluster")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:g,output:h,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The clustering strategy could not be interpreted.",http:422,when:"Query is too vague or context graph has no clusterable structure."}}},policy:{auth:"user"}});const m=new t({name:"GraphSuggestInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1},maxSuggestions:{type:e.Int_unsecure(),isOptional:!0}}});const y=new t({name:"GraphSuggestOutput",fields:{suggestions:{type:e.JSONObject(),isOptional:!1},truncated:{type:e.Boolean(),isOptional:!1}}});export const GraphSuggestDocBlock={id:"docs.tech.graph.suggest",title:"graph.suggest \u2014 AI graph-edit suggestions",summary:"Ranked read-only graph-edit suggestions. Mutations require explicit user confirmation. Budget: 2 000 in / 800 out / $0.020.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.suggest
+
+Returns ranked suggestions for graph edits based on a natural-language request.
+
+**Read-only**: suggestions are never auto-applied. Each must be confirmed via
+the AI suggestion confirmation UX (W7.4) before any mutation occurs.
+
+## Output shape
+\`suggestions: Array<{ id, label, description, confidence, action }>\`
+
+## Truncation
+Output >800 tokens is halted mid-stream; \`truncated: true\` is returned.
+Users may request expansion.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=2 000 \xB7 maxOutputTokens=800 \xB7 hardCapUsd=$0.020`};export const GraphSuggestCommand=r({meta:{key:"graph.suggest",title:"Graph suggest",version:"1.0.0",description:"Ranked read-only AI suggestions for graph edits.",goal:"Surface AI-driven graph improvement ideas without auto-applying mutations.",context:["Suggestions require explicit human confirmation (W7.4) before any mutation.","Output truncated at 800 tokens \u2014 truncated=true indicates partial result.","Budget: maxInputTokens=2000, maxOutputTokens=800, hardCapUsd=$0.020.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.suggest")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:m,output:y,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The suggestion request could not be interpreted.",http:422,when:"Query is empty, contradictory, or the context graph is empty."}}},policy:{auth:"user"}});

package/dist/agent/commands/graphRefactor.command.d.ts

@@ -0,0 +1,86 @@
+/**
+ * graph.refactor — LLM-facing command for pattern-level graph transformations (M5 P2/W2.2).
+ *
+ * Four transformation types, each selected by the `operation.type` discriminant:
+ *  - `rename_by_pattern` — regex/glob label rename across nodes, edges, or both
+ *  - `extract_subgraph`  — move a set of nodes (+ incident edges) into a new sub-graph
+ *  - `merge_nodes`       — collapse multiple nodes into one, re-routing all edges
+ *  - `split_node`        — expand one node into multiple, partitioned by supplied groups
+ *
+ * Supports `dryRun: true` to preview the change set without mutating state.
+ *
+ * Per-call budget: 2 000 in / 600 out / $0.015 (Anthropic Sonnet-4 reference).
+ * All invocations emit an `ai.graph.refactor` observability event.
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * Per-call budget for `graph.refactor`.
+ * Larger than `graph.edit` to accommodate pattern analysis over the full graph.
+ */
+export declare const GRAPH_REFACTOR_BUDGET: {
+    readonly maxInputTokens: 2000;
+    readonly maxOutputTokens: 600;
+    readonly hardCapUsd: 0.035;
+};
+export declare const GraphRefactorDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphRefactorCommand: import("../..").OperationSpec<SchemaModel<{
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /**
+     * Discriminated operation object. Must have a `type` field matching one of:
+     * `rename_by_pattern` | `extract_subgraph` | `merge_nodes` | `split_node`.
+     */
+    operation: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /**
+     * When `true`, returns a preview of what would change without mutating state.
+     * Useful for the suggestion confirmation UX before committing.
+     * @default false
+     */
+    dryRun: {
+        type: import("@lssm/lib.schema").FieldType<boolean, boolean>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    /**
+     * Structural diff: lists all nodes/edges that would be (or were) added,
+     * removed, or modified.
+     */
+    preview: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /**
+     * `false` when `dryRun: true` — no state was mutated.
+     * `true` when the operation was applied to the graph.
+     */
+    applied: {
+        type: import("@lssm/lib.schema").FieldType<boolean, boolean>;
+        isOptional: false;
+    };
+    /**
+     * Present for `extract_subgraph`: the ID of the newly created sub-graph.
+     */
+    resultGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    /** Actual token + cost consumption for this call. */
+    budgetUsed: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/agent/commands/graphRefactor.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as r}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as o,AGENT_OWNERS as n,AGENT_STABILITY as s,AGENT_TAGS as p}from"../constants.js";export const GRAPH_REFACTOR_BUDGET={maxInputTokens:2000,maxOutputTokens:600,hardCapUsd:0.035};const i=[...p,"graph","ai","refactor","pattern","m5"];const d=new t({name:"GraphRefactorInput",fields:{contextGraphId:{type:e.ID(),isOptional:!1},operation:{type:e.JSONObject(),isOptional:!1},dryRun:{type:e.Boolean(),isOptional:!0}}});const u=new t({name:"GraphRefactorOutput",fields:{preview:{type:e.JSONObject(),isOptional:!1},applied:{type:e.Boolean(),isOptional:!1},resultGraphId:{type:e.ID(),isOptional:!0},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphRefactorDocBlock={id:"docs.tech.graph.refactor",title:"graph.refactor \u2014 pattern-level graph transformations",summary:"Four structural refactoring ops: rename-by-pattern, extract-subgraph, merge-nodes, split-node. Supports dryRun preview. Budget: 2 000 in / 600 out / $0.035.",kind:"reference",visibility:"public",route:"/docs/tech/graph/refactor",tags:["automation","agent","execution","graph","ai","refactor","pattern","m5"],body:'# graph.refactor\n\nApplies a single pattern-level structural transformation to a graph. Choose the\noperation type via `operation.type`.\n\n## Supported operations\n\n### `rename_by_pattern`\nRenames node/edge labels matching a JS regex pattern.\n`scope`: `"nodes"` | `"edges"` | `"both"`.\n\n### `extract_subgraph`\nMoves specified nodes (and edges between them) into a new sub-graph.\nCross-boundary edges are preserved as stubs. Returns `resultGraphId`.\n\n### `merge_nodes`\nCollapses `sourceNodeIds` into `targetNodeId`.\n`strategy`: `"union"` (all edges kept) | `"intersect"` (shared edges only).\n\n### `split_node`\nExpands one node into multiple partitions. Edges re-distributed by kind affinity.\n\n## Dry run\n\nPass `dryRun: true` to preview the diff without mutating state.\nThe `preview` field in the output is always populated; `applied` is `false`.\n\n## Budget (M5 P2/W2.2)\nmaxInputTokens=2 000 \xB7 maxOutputTokens=600 \xB7 hardCapUsd=$0.035'};export const GraphRefactorCommand=a({meta:{key:"graph.refactor",title:"Graph refactor",version:"1.0.0",description:"Pattern-level graph transformations: rename-by-pattern, extract-subgraph, merge-nodes, split-node.",goal:"Let AI agents restructure graphs at the pattern level, with dry-run preview support.",context:["Discriminated by operation.type: rename_by_pattern | extract_subgraph | merge_nodes | split_node.","dryRun: true returns a structural diff preview without mutating state.","extract_subgraph emits resultGraphId for the new sub-graph.","Budget: maxInputTokens=2000, maxOutputTokens=600, hardCapUsd=$0.035.","Emits ai.graph.refactor observability event on every invocation."].join(" "),domain:o,owners:n,tags:i,stability:s,docId:[r("docs.tech.graph.refactor")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:d,output:u,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_OPERATION:{description:"The operation object has an unknown type or missing required fields.",http:422,when:"operation.type is not one of the four supported values, or required fields are absent."},ENTITY_NOT_FOUND:{description:"A referenced nodeId or edgeId does not exist in the graph.",http:404,when:"operation references nodes/edges not present in contextGraphId."},INVALID_PATTERN:{description:"The regex pattern in rename_by_pattern is syntactically invalid.",http:422,when:"operation.pattern cannot be compiled as a JavaScript RegExp."},MERGE_TARGET_NOT_IN_SOURCES:{description:"targetNodeId must be one of the sourceNodeIds.",http:422,when:"merge_nodes operation has targetNodeId not in sourceNodeIds."}}},policy:{auth:"user"}});

package/dist/agent/commands/graphSuggestEvolution.command.d.ts

@@ -0,0 +1,90 @@
+/**
+ * graph.suggest_evolution — proactive AI suggestions based on graph state (M5 P2/W2.4).
+ *
+ * Analyses the current graph for structural and semantic weaknesses and returns
+ * ranked suggestions. Each suggestion carries a `kind` discriminant that maps to
+ * a specific pattern the graph is missing or that would improve it:
+ *
+ *  - `missing_reviewer`      — a node/flow has no assigned reviewer or approval step
+ *  - `missing_retry`         — an error path has no retry or back-off edge
+ *  - `weak_path`             — a critical path has only one route (no redundancy)
+ *  - `isolated_node`         — a node has no incoming or outgoing edges
+ *  - `naming_inconsistency`  — node/edge labels diverge from the dominant naming style
+ *  - `missing_feedback_loop` — a workflow has no feedback or notification branch
+ *  - `circular_dependency`   — a cycle exists that may indicate a design issue
+ *  - `high_fan_out`          — a node has an unusually large number of outgoing edges
+ *
+ * Suggestions are read-only — no mutations are applied. Each includes a
+ * `suggestedFix` description the user can send back to `graph.edit` or
+ * `graph.compose` for execution.
+ *
+ * Per-call budget: 2 500 in / 1 000 out / $0.028 (Anthropic Sonnet-4 reference).
+ * All invocations emit an `ai.graph.suggest_evolution` observability event.
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * Per-call budget for `graph.suggest_evolution`.
+ * Needs the full graph context to spot structural patterns; output is concise ranked list.
+ */
+export declare const GRAPH_SUGGEST_EVOLUTION_BUDGET: {
+    readonly maxInputTokens: 2500;
+    readonly maxOutputTokens: 1000;
+    readonly hardCapUsd: 0.028;
+};
+export declare const GraphSuggestEvolutionDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const GraphSuggestEvolutionCommand: import("../..").OperationSpec<SchemaModel<{
+    /** ID of the graph to analyse for evolution suggestions. */
+    contextGraphId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /**
+     * Narrows the suggestion scan to one concern area.
+     * One of: `"reliability"` | `"coverage"` | `"connectivity"` | `"naming"` | `"all"`.
+     * @default "all"
+     */
+    focusArea: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    /**
+     * Maximum number of suggestions to return.
+     * @default 5
+     * @max 20
+     */
+    maxSuggestions: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    /**
+     * Ranked list of evolution suggestions, highest confidence/severity first.
+     * Each element conforms to the EvolutionSuggestion shape described above.
+     */
+    suggestions: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+    /**
+     * `true` when the output token budget was reached before all suggestions
+     * could be serialised. The user may narrow `focusArea` to get full detail.
+     */
+    truncated: {
+        type: import("@lssm/lib.schema").FieldType<boolean, boolean>;
+        isOptional: false;
+    };
+    /** Actual token + cost consumption for this call. */
+    budgetUsed: {
+        type: import("@lssm/lib.schema").FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/agent/commands/graphSuggestEvolution.command.js

@@ -0,0 +1,35 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as o}from"../../docs/registry.js";import{defineCommand as n}from"../../operations/index.js";import{AGENT_DOMAIN as s,AGENT_OWNERS as i,AGENT_STABILITY as a,AGENT_TAGS as r}from"../constants.js";export const GRAPH_SUGGEST_EVOLUTION_BUDGET={maxInputTokens:2500,maxOutputTokens:1000,hardCapUsd:0.028};const u=[...r,"graph","ai","evolution","suggestions","m5"];const g=new t({name:"GraphSuggestEvolutionInput",fields:{contextGraphId:{type:e.ID(),isOptional:!1},focusArea:{type:e.String_unsecure(),isOptional:!0},maxSuggestions:{type:e.Int_unsecure(),isOptional:!0}}});const c=new t({name:"GraphSuggestEvolutionOutput",fields:{suggestions:{type:e.JSONObject(),isOptional:!1},truncated:{type:e.Boolean(),isOptional:!1},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphSuggestEvolutionDocBlock={id:"docs.tech.graph.suggest-evolution",title:"graph.suggest_evolution \u2014 proactive graph evolution suggestions",summary:"Ranks structural and semantic improvement suggestions for a graph: missing reviewer, missing retry, weak path, isolated node, naming inconsistency, missing feedback loop, circular dependency, high fan-out. Budget: 2 500 in / 1 000 out / $0.028.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest-evolution",tags:["automation","agent","execution","graph","ai","evolution","suggestions","m5"],body:`# graph.suggest_evolution
+
+Analyses the current graph and returns ranked proactive improvement suggestions.
+Suggestions are **read-only** \u2014 nothing is applied automatically.
+
+## Suggestion kinds
+
+| kind | Description |
+|---|---|
+| \`missing_reviewer\` | A node or flow has no assigned reviewer / approval step |
+| \`missing_retry\`    | An error path has no retry or back-off edge |
+| \`weak_path\`        | A critical path has only one route (no redundancy) |
+| \`isolated_node\`    | A node has neither incoming nor outgoing edges |
+| \`naming_inconsistency\` | Labels diverge from the dominant naming style |
+| \`missing_feedback_loop\` | A workflow has no feedback or notification branch |
+| \`circular_dependency\` | A cycle exists that may indicate a design issue |
+| \`high_fan_out\`     | A node has an unusually large number of outgoing edges |
+
+## focusArea
+
+Narrow the scan to reduce cost and noise:
+- \`"reliability"\` \u2014 retry, redundancy, failure-path coverage
+- \`"coverage"\`    \u2014 reviewer presence, approval steps, feedback loops
+- \`"connectivity"\` \u2014 isolated nodes, weak paths, high fan-out
+- \`"naming"\`      \u2014 label consistency
+- \`"all"\`         \u2014 full scan (default)
+
+## Acting on suggestions
+
+Each suggestion includes a \`suggestedFix\` string.
+Pass that text back to \`graph.edit\` or \`graph.compose\` to apply the fix
+after confirming through the AI suggestion UX (W7.4).
+
+## Budget (M5 P2/W2.4)
+maxInputTokens=2 500 \xB7 maxOutputTokens=1 000 \xB7 hardCapUsd=$0.028`};export const GraphSuggestEvolutionCommand=n({meta:{key:"graph.suggest_evolution",title:"Graph suggest evolution",version:"1.0.0",description:"Proactive ranked suggestions for improving graph structure and coverage.",goal:"Surface structural and semantic weaknesses (missing retry, weak path, etc.) before they become incidents.",context:["Returns EvolutionSuggestion[] ranked by confidence \xD7 severity.","Kinds: missing_reviewer | missing_retry | weak_path | isolated_node |","naming_inconsistency | missing_feedback_loop | circular_dependency | high_fan_out.","focusArea narrows the scan: reliability | coverage | connectivity | naming | all.","maxSuggestions defaults to 5, max 20. truncated=true when output budget hit.","Read-only \u2014 no mutations applied. suggestedFix text guides follow-up graph.edit calls.","Budget: maxInputTokens=2500, maxOutputTokens=1000, hardCapUsd=$0.028.","Emits ai.graph.suggest_evolution observability event on every invocation."].join(" "),domain:s,owners:i,tags:u,stability:a,docId:[o("docs.tech.graph.suggest-evolution")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:g,output:c,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},EMPTY_GRAPH:{description:"The graph has no nodes or edges to analyse.",http:422,when:"contextGraphId references a graph with zero nodes."},CONTEXT_GRAPH_NOT_FOUND:{description:"The supplied contextGraphId does not exist.",http:404,when:"contextGraphId references a graph that cannot be found."},INVALID_FOCUS_AREA:{description:"The focusArea value is not one of the supported categories.",http:422,when:"focusArea is provided but is not reliability | coverage | connectivity | naming | all."}}},policy:{auth:"user"}});

package/dist/agent/commands/index.d.ts

@@ -0,0 +1,9 @@
+export * from './agentApprovals.command.js';
+export * from './agentCancel.command.js';
+export * from './agentRun.command.js';
+export * from './agentTaskOps.command.js';
+export * from './graphCompose.command.js';
+export * from './graphEdit.command.js';
+export * from './graphOps.command.js';
+export * from './graphRefactor.command.js';
+export * from './graphSuggestEvolution.command.js';

package/dist/agent/commands/index.js

@@ -0,0 +1 @@
+export*from"./agentApprovals.command.js";export*from"./agentCancel.command.js";export*from"./agentRun.command.js";export*from"./agentTaskOps.command.js";export*from"./graphCompose.command.js";export*from"./graphEdit.command.js";export*from"./graphOps.command.js";export*from"./graphRefactor.command.js";export*from"./graphSuggestEvolution.command.js";

package/dist/agent/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const AGENT_DOMAIN = "agent";
+export declare const AGENT_OWNERS: string[];
+export declare const AGENT_TAGS: string[];
+export declare const AGENT_STABILITY: "beta";

package/dist/agent/constants.js

@@ -0,0 +1 @@
+import{StabilityEnum as t,TagsEnum as o}from"../ownership.js";export const AGENT_DOMAIN="agent";export const AGENT_OWNERS=["platform.ai"];export const AGENT_TAGS=[o.Automation,"agent","execution"];export const AGENT_STABILITY=t.Beta;