@boboddy/sdk 0.5.1 → 0.5.2

package/dist/definitions/validation/validation-issue.d.ts

@@ -0,0 +1,52 @@
+export type DefinitionValidationIssue = {
+    readonly check: "signal-source-path" | "route-target" | "signal-binding" | "health-check-mcp-server" | "health-check-double-qualified" | "unbound-required-input" | "binding-target-field" | "binding-type-mismatch";
+    /**
+     * Whether this issue blocks a push. The 4 original checks are all
+     * unconditionally `"error"`, matching their implicit all-blocking
+     * behavior before this field existed. `"binding-type-mismatch"` is a
+     * `"warning"`-tier check — a resolved type disagreement is worth
+     * surfacing but, per §4's own bias, never provably a runtime failure the
+     * way an unresolved binding or a missing required input is.
+     * `"binding-target-field"`'s "unbound field name isn't a declared
+     * `additionalInput`" sub-check is `"info"`-tier — passing extra context
+     * a step doesn't declare as an `additionalInput` is allowed (the value is
+     * just dropped), so it's worth surfacing for awareness but never rises to
+     * even a warning. Only `assertValidDefinitionSpecs` treats these tiers
+     * differently: it blocks a push on `"error"` alone.
+     */
+    readonly severity: "error" | "warning" | "info";
+    readonly message: string;
+    /**
+     * The pipeline this issue belongs to, when the check is pipeline-scoped
+     * (`route-target`/`signal-binding`/the three Phase 2 binding checks) —
+     * absent for step-only checks (`signal-source-path`/`health-check-*`),
+     * which have no pipeline context of their own. Required before the
+     * designer (Phase 5) can attach an error to the right graph node.
+     */
+    readonly pipelineKey?: string;
+    /** The node this issue is about, when pipeline-scoped. */
+    readonly nodeKey?: string;
+    /**
+     * A second, related node this issue is about — e.g. `signal-binding`'s
+     * producer node, when different from `nodeKey`'s consumer. Absent when
+     * the issue is about a single node, or when the "other end" isn't a
+     * node in this pipeline at all (`route-target`'s target is a different
+     * *pipeline*, not a node).
+     */
+    readonly targetNodeKey?: string;
+    /**
+     * The specific `parallel` branch this issue is about, when `nodeKey`
+     * names a `parallel` node — one of that node's `branches` keys. Set only
+     * by the three Phase 2 binding checks (`unbound-required-input`/
+     * `binding-target-field`/`binding-type-mismatch`) when the
+     * `BindingContext` they're walking is a `parallel` branch's own bindings
+     * (`bindingContexts`' `ctx.branchKey`), not the node's own bindings.
+     * Absent for every other check, and absent for those three checks' own
+     * non-`parallel` (`step`/`fanOut`/`loop`) cases — without this, issues
+     * from two different branches of the same `parallel` node are
+     * indistinguishable by branch.
+     */
+    readonly branchKey?: string;
+};
+/** Formats a path list for an error message, capped so it stays readable. */
+export declare function listPaths(paths: readonly string[], limit?: number): string;

package/dist/generated/types.gen.d.ts

@@ -4814,6 +4814,7 @@ export type PostApiPipelineDefinitionsData = {
                 [key: string]: unknown;
             } | unknown;
         }>;
+        entryNodeKey?: string;
     };
     path?: never;
     query?: never;
@@ -5260,6 +5261,7 @@ export type PutApiPipelineDefinitionsData = {
                 [key: string]: unknown;
             } | unknown;
         }>;
+        entryNodeKey?: string;
     };
     path?: never;
     query?: never;

package/dist/index.js

@@ -16126,6 +16126,12 @@ ${feature._promptAddition}` : feature._promptAddition;
 }
 // src/definitions/steps/define-code-step.ts
 function codeStep(config2) {
+  const features = config2.features ?? [];
+  let effectiveResult = config2.resultSchema;
+  for (const feature of features) {
+    effectiveResult = effectiveResult ? effectiveResult.extend(feature._resultExtension.shape) : feature._resultExtension;
+  }
+  const featureSignals = features.flatMap((f) => f._signals);
   const spec = {
     key: config2.key,
     name: config2.name,
@@ -16135,14 +16141,23 @@ function codeStep(config2) {
     status: config2.status ?? "active",
     prompt: null,
     inputSchemaJson: config2.inputSchema ? toJSONSchema(config2.inputSchema) : null,
-    resultSchemaJson: config2.resultSchema ? toJSONSchema(config2.resultSchema) : null,
-    signalExtractorDefinitions: (config2.signals ?? []).map((signal) => ({
-      key: signal.key ?? signal.sourcePath,
-      sourcePath: signal.sourcePath,
-      type: signal.type,
-      required: signal.required ?? true,
-      availableWhenResultStatusIn: signal.availableWhenResultStatusIn ?? null
-    })),
+    resultSchemaJson: effectiveResult ? toJSONSchema(effectiveResult) : null,
+    signalExtractorDefinitions: [
+      ...(config2.signals ?? []).map((signal) => ({
+        key: signal.key ?? signal.sourcePath,
+        sourcePath: signal.sourcePath,
+        type: signal.type,
+        required: signal.required ?? true,
+        availableWhenResultStatusIn: signal.availableWhenResultStatusIn ?? null
+      })),
+      ...featureSignals.map((signal) => ({
+        key: signal.key,
+        sourcePath: signal.sourcePath,
+        type: signal.type,
+        required: signal.required ?? true,
+        availableWhenResultStatusIn: signal.availableWhenResultStatusIn ?? null
+      }))
+    ],
     opencodeMcpJson: null,
     opencodePluginJson: null,
     healthChecksJson: null,
@@ -16205,20 +16220,29 @@ var buildStepDefinitionsClient = (stepDefinitions) => {
   };
 };
 // src/definitions/steps/step-features.ts
+var notificationKindSchema = exports_external.enum([
+  "feedback_request",
+  "status_update",
+  "blocked",
+  "result_ready",
+  "warning"
+]);
+var notificationPrioritySchema = exports_external.enum(["low", "normal", "high", "urgent"]);
+var notificationChannelSchema = exports_external.enum([
+  "in_app",
+  "work_item_platform_comment",
+  "email",
+  "slack"
+]);
 var NOTIFICATION_SIGNAL_KEY = "$boboddy_notifications_v1";
 var NOTIFICATION_RESULT_KEY = "$boboddy_notifications_v1";
+var DEFAULT_NOTIFICATION_KIND = "status_update";
 var notificationItemSchema = exports_external.object({
-  kind: exports_external.enum([
-    "feedback_request",
-    "status_update",
-    "blocked",
-    "result_ready",
-    "warning"
-  ]).describe("The kind of user notification."),
+  kind: notificationKindSchema.describe("The kind of user notification."),
   title: exports_external.string().describe("Short, human-readable notification title."),
   body: exports_external.string().describe("The notification body / details."),
-  priority: exports_external.enum(["low", "normal", "high", "urgent"]).describe("How important this notification is for the user."),
-  suggestedChannels: exports_external.array(exports_external.enum(["in_app", "work_item_platform_comment", "email", "slack"])).optional().describe("Channels the agent thinks are worth using. The platform policy decides the final channels."),
+  priority: notificationPrioritySchema.describe("How important this notification is for the user."),
+  suggestedChannels: exports_external.array(notificationChannelSchema).optional().describe("Channels the agent thinks are worth using. The platform policy decides the final channels."),
   payload: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe('Kind-specific structured data. For "feedback_request": { category, urgency, suggestedKey? }.')
 }).describe("A single user notification emitted by the agent.");
 var notificationsFeature = {
@@ -16248,23 +16272,62 @@ var notificationsFeature = {
     }
   ]
 };
+var feedbackRequestsFeature = {
+  _resultExtension: exports_external.object({
+    [NOTIFICATION_RESULT_KEY]: exports_external.array(notificationItemSchema.extend({ kind: exports_external.literal("feedback_request") })).optional()
+  }),
+  _promptAddition: [
+    "## Feedback Requests",
+    "",
+    `If you need to ask a human a clarifying question, populate the \`${NOTIFICATION_RESULT_KEY}\` array with items of kind \`"feedback_request"\`.`,
+    "Each item must include:",
+    "- **title**: A short, human-readable summary of the question.",
+    "- **body**: The full question.",
+    "- **priority**: One of `low`, `normal`, `high`, `urgent`.",
+    '- **payload**: `{ "category": string, "urgency": "blocking"|"clarification"|"assumption"|"informational", "suggestedKey"?: string }`.'
+  ].join(`
+`),
+  _signals: notificationsFeature._signals
+};
 var Features = {
-  notifications: Object.assign(() => notificationsFeature, {
-    signal: {
-      key: NOTIFICATION_SIGNAL_KEY,
-      find(signals) {
-        const match = signals.find((s) => s.key === NOTIFICATION_SIGNAL_KEY);
-        if (!match)
-          return;
-        const parsed = exports_external.array(notificationItemSchema).safeParse(match.valueJson);
-        return parsed.success ? parsed.data : undefined;
-      }
-    }
+  notifications: () => notificationsFeature,
+  feedbackRequests: () => feedbackRequestsFeature
+};
+var NotificationSignal = {
+  key: NOTIFICATION_SIGNAL_KEY,
+  find(signals) {
+    const match = signals.find((s) => s.key === NOTIFICATION_SIGNAL_KEY);
+    if (!match)
+      return;
+    const parsed = exports_external.array(notificationItemSchema).safeParse(match.valueJson);
+    return parsed.success ? parsed.data : undefined;
+  }
+};
+var Notify = {
+  create: (item) => ({
+    [NOTIFICATION_RESULT_KEY]: [item]
+  }),
+  inApp: (title, body, priority, options) => Notify.create({
+    kind: options?.kind ?? DEFAULT_NOTIFICATION_KIND,
+    title,
+    body,
+    priority,
+    suggestedChannels: ["in_app"],
+    ...options?.payload ? { payload: options.payload } : {}
   }),
-  feedbackRequests: Object.assign(() => notificationsFeature, {
-    signal: {
-      key: NOTIFICATION_SIGNAL_KEY
+  feedbackRequest: (question, category, urgency, suggestedKey) => Notify.create({
+    kind: "feedback_request",
+    title: question,
+    body: question,
+    priority: "normal",
+    payload: {
+      category,
+      urgency,
+      ...suggestedKey ? { suggestedKey } : {}
     }
+  }),
+  merge: (...fragments) => ({
+    [NOTIFICATION_RESULT_KEY]: fragments.flatMap((fragment) => fragment[NOTIFICATION_RESULT_KEY])
   })
 };
 // src/definitions/advancement-policies/define-advancement-policy.ts
@@ -16961,25 +17024,6 @@ function compileLoopState(stateKey, state, ctx) {
 function compileTerminalState(stateKey, kind) {
   return { nodeDefinitions: [{ nodeKey: stateKey, kind }], edges: [] };
 }
-function assertNoIllegalConvergentEdges(pipelineKey, nodeKindByKey, edges) {
-  const incoming = new Map;
-  for (const edge of edges) {
-    const list = incoming.get(edge.toNodeKey) ?? [];
-    list.push(edge);
-    incoming.set(edge.toNodeKey, list);
-  }
-  for (const [targetKey, incomingEdges] of incoming) {
-    if (incomingEdges.length <= 1)
-      continue;
-    const hasInvalidSource = incomingEdges.some((edge) => {
-      const kind = nodeKindByKey.get(edge.fromNodeKey);
-      return kind !== "choice" && kind !== "loop";
-    });
-    if (hasInvalidSource) {
-      throw new Error(`Pipeline "${pipelineKey}": state "${targetKey}" has more than one incoming edge, but not every source is a 'choice'/'loop' state (unconditional convergent edges are not allowed \u2014 see docs/research/flat-pipeline-sdk-and-visual-designer.md \xA76).`);
-    }
-  }
-}
 
 // src/definitions/pipelines/define-pipeline.ts
 function isWorkingNodeDefinition(node) {
@@ -17016,8 +17060,6 @@ function definePipeline(config2) {
     nodeDefinitions.push(...compiled.nodeDefinitions);
     dependencyEdges.push(...compiled.edges);
   }
-  const nodeKindByKey = new Map(nodeDefinitions.map((node) => [node.nodeKey, node.kind]));
-  assertNoIllegalConvergentEdges(config2.key, nodeKindByKey, dependencyEdges);
   let inputSchemaJson = null;
   if (config2.input) {
     try {
@@ -17033,6 +17075,7 @@ function definePipeline(config2) {
     version: config2.version ?? 1,
     status: config2.status ?? "active",
     inputSchemaJson,
+    entryNodeKey: config2.startAt,
     _stepDefinitions: [...stepDefMap.values()],
     nodeDefinitions,
     dependencyEdges
@@ -17145,6 +17188,7 @@ var buildPipelineDefinitionsClient = (pipelineDefinitions) => {
         description: spec.description,
         status: spec.status,
         inputSchemaJson: spec.inputSchemaJson,
+        entryNodeKey: spec.entryNodeKey,
         nodeDefinitions,
         dependencyEdges
       };
@@ -17624,6 +17668,8 @@ export {
   Features,
   GitHubIntegrations,
   NotificationRules,
+  NotificationSignal,
+  Notify,
   PipelineDefinitions,
   PipelineExecutions,
   ProjectContext,