@ddse/acm-examples 0.5.0

package/src/tasks/entitlement.ts

@@ -0,0 +1,197 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+import type { CustomerProfile } from '../data/entitlement.js';
+import {
+  type FetchCustomerProfileInput,
+  type FetchCustomerProfileOutput,
+  type EvaluateEntitlementInput,
+  type EvaluateEntitlementOutput,
+  type NotifySupervisorInput as EntitlementNotifySupervisorInput,
+  type NotifySupervisorOutput as EntitlementNotifySupervisorOutput,
+} from '../tools/entitlement/index.js';
+
+export class RetrieveCustomerProfileTask extends Task<
+  FetchCustomerProfileInput,
+  FetchCustomerProfileOutput
+> {
+  constructor() {
+    super('task-entitlement-fetch-customer', 'entitlement.fetch_customer_profile');
+  }
+
+  idemKey(_ctx: RunContext, input: FetchCustomerProfileInput): string | undefined {
+    return input?.customerId ? `entitlement:customer:${input.customerId}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: FetchCustomerProfileInput): Record<string, unknown> {
+    return {
+      action: 'fetch_customer_profile',
+      customerId: input.customerId,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.customer !== undefined'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: FetchCustomerProfileInput
+  ): Promise<FetchCustomerProfileOutput> {
+    const tool = ctx.getTool('fetch_customer_profile');
+    if (!tool) {
+      throw new Error('fetch_customer_profile tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as FetchCustomerProfileOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'customer_profile_loaded',
+      customerId: input.customerId,
+    });
+    return result;
+  }
+}
+
+export interface EvaluateEntitlementTaskInput extends EvaluateEntitlementInput {
+  customer?: CustomerProfile;
+}
+
+export class EvaluateEntitlementTask extends Task<
+  EvaluateEntitlementTaskInput,
+  EvaluateEntitlementOutput
+> {
+  constructor() {
+    super('task-entitlement-evaluate', 'entitlement.evaluate');
+  }
+
+  policyInput(_ctx: RunContext, input: EvaluateEntitlementTaskInput): Record<string, unknown> {
+    return {
+      action: 'evaluate_entitlement',
+      customerId: input.customerId,
+      benefitCode: input.benefitCode,
+    };
+  }
+
+  verification(): string[] {
+    return [
+      "output.decision === 'allow' || output.decision === 'deny'",
+      'output.policy !== undefined',
+      'Array.isArray(output.rationale)',
+    ];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: EvaluateEntitlementTaskInput
+  ): Promise<EvaluateEntitlementOutput> {
+    const tool = ctx.getTool('evaluate_entitlement');
+    if (!tool) {
+      throw new Error('evaluate_entitlement tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as EvaluateEntitlementOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'entitlement_evaluated',
+      customerId: input.customerId,
+      benefitCode: input.benefitCode,
+      decision: result.decision,
+      violations: result.violations,
+    });
+    return result;
+  }
+}
+
+export type SupervisorNotificationTaskInput = EntitlementNotifySupervisorInput & {
+  decision: 'allow' | 'deny';
+};
+
+export class SupervisorNotificationTask extends Task<
+  SupervisorNotificationTaskInput,
+  EntitlementNotifySupervisorOutput
+> {
+  constructor() {
+    super('task-entitlement-notify-supervisor', 'entitlement.notify_supervisor');
+  }
+
+  policyInput(_ctx: RunContext, input: SupervisorNotificationTaskInput): Record<string, unknown> {
+    return {
+      action: 'notify_supervisor',
+      customerId: input.customerId,
+      channel: input.channel ?? 'email',
+      decision: input.decision,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.notified === true', 'typeof output.messageId === "string"'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: SupervisorNotificationTaskInput
+  ): Promise<EntitlementNotifySupervisorOutput> {
+    const tool = ctx.getTool('notify_supervisor');
+    if (!tool) {
+      throw new Error('notify_supervisor tool is not registered');
+    }
+
+    const normalizedInput: SupervisorNotificationTaskInput = {
+      ...input,
+    };
+
+    const evaluationOutput = ctx.outputs?.['task-entitlement-evaluate'] ?? {};
+    const customerProfile = ctx.outputs?.['task-entitlement-fetch-customer']?.customer ?? {};
+
+    const normalizeString = (value: unknown): string | undefined => {
+      if (typeof value !== 'string') {
+        return undefined;
+      }
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : undefined;
+    };
+
+    const customerId =
+      normalizeString(normalizedInput.customerId) ??
+      normalizeString(evaluationOutput?.customer?.id) ??
+      normalizeString(customerProfile?.id) ??
+      normalizeString(ctx.context?.facts?.customerId);
+    if (customerId) {
+      normalizedInput.customerId = customerId.toUpperCase();
+    }
+
+    const benefitCode =
+      normalizeString(evaluationOutput?.policy?.benefitCode) ??
+      normalizeString(ctx.context?.facts?.benefitCode);
+    const benefitCodeUpper = benefitCode ? benefitCode.toUpperCase() : undefined;
+
+    if (!normalizeString(normalizedInput.channel)) {
+      normalizedInput.channel = 'email';
+    }
+
+    const decision =
+      (normalizeString(normalizedInput.decision)?.toLowerCase() as 'allow' | 'deny' | undefined) ??
+      evaluationOutput?.decision ??
+      'allow';
+    normalizedInput.decision = decision;
+
+    if (!normalizeString(normalizedInput.message)) {
+      const customerName =
+        normalizeString(customerProfile?.name) ??
+        normalizeString(evaluationOutput?.customer?.name) ??
+        'customer';
+  const renderedBenefit = benefitCodeUpper ?? 'benefit';
+      const renderedCustomer = normalizedInput.customerId ?? 'UNKNOWN-ID';
+      normalizedInput.message = `Entitlement decision ${decision} for ${customerName} (${renderedCustomer}) regarding ${renderedBenefit}.`;
+    }
+
+    const result = (await tool.call(normalizedInput)) as EntitlementNotifySupervisorOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'supervisor_notified',
+      customerId: normalizedInput.customerId,
+      decision: normalizedInput.decision,
+      channel: result.channel,
+    });
+    return result;
+  }
+}

package/src/tasks/incidents.ts

@@ -0,0 +1,277 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+import type { IncidentRecord, IncidentSeverity } from '../data/incidents.js';
+import {
+  type FetchIncidentInput,
+  type FetchIncidentOutput,
+  type ClassifySeverityOutput,
+  type SelectQueueOutput,
+  type EscalateIncidentInput,
+  type EscalateIncidentOutput,
+} from '../tools/incidents/index.js';
+
+export class FetchIncidentTask extends Task<FetchIncidentInput, FetchIncidentOutput> {
+  constructor() {
+    super('task-incident-fetch', 'incident.fetch');
+  }
+
+  idemKey(_ctx: RunContext, input: FetchIncidentInput): string | undefined {
+    return input?.incidentId ? `incident:${input.incidentId}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: FetchIncidentInput): Record<string, unknown> {
+    return {
+      action: 'fetch_incident',
+      incidentId: input.incidentId,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.incident !== undefined'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: FetchIncidentInput
+  ): Promise<FetchIncidentOutput> {
+    const tool = ctx.getTool('fetch_incident');
+    if (!tool) {
+      throw new Error('fetch_incident tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as FetchIncidentOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'incident_loaded',
+      incidentId: input.incidentId,
+    });
+    return result;
+  }
+}
+
+export interface ClassifySeverityTaskInput {
+  incident?: IncidentRecord;
+  incidentId?: string;
+}
+
+export class ClassifySeverityTask extends Task<
+  ClassifySeverityTaskInput,
+  ClassifySeverityOutput
+> {
+  constructor() {
+    super('task-incident-classify', 'incident.classify_severity');
+  }
+
+  policyInput(_ctx: RunContext, input: ClassifySeverityTaskInput): Record<string, unknown> {
+    const incident = this.resolveIncident(_ctx, input);
+    return {
+      action: 'classify_severity',
+      incidentId: incident?.id ?? input.incidentId,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.severity !== undefined', 'typeof output.score === "number"'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: ClassifySeverityTaskInput
+  ): Promise<ClassifySeverityOutput> {
+    const tool = ctx.getTool('classify_severity');
+    if (!tool) {
+      throw new Error('classify_severity tool is not registered');
+    }
+
+    const incident = this.resolveIncident(ctx, input);
+    if (!incident) {
+      throw new Error('incident is required');
+    }
+
+    const result = (await tool.call({ incident })) as ClassifySeverityOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'incident_severity_classified',
+      incidentId: incident.id,
+      severity: result.severity,
+      score: result.score,
+    });
+    return result;
+  }
+
+  private resolveIncident(
+    ctx: RunContext,
+    input: ClassifySeverityTaskInput
+  ): IncidentRecord | undefined {
+    if (input?.incident) {
+      return input.incident;
+    }
+
+    const fetchOutput = ctx.outputs?.['task-incident-fetch'] as FetchIncidentOutput | undefined;
+    const incident = fetchOutput?.incident;
+    if (!incident) {
+      return undefined;
+    }
+
+    if (!input?.incidentId || incident.id === input.incidentId) {
+      return incident;
+    }
+
+    return undefined;
+  }
+}
+
+export interface SelectQueueTaskInput {
+  incident?: IncidentRecord;
+  incidentId?: string;
+  severityOverride?: IncidentSeverity;
+}
+
+export class SelectQueueTask extends Task<SelectQueueTaskInput, SelectQueueOutput> {
+  constructor() {
+    super('task-incident-route', 'incident.select_queue');
+  }
+
+  policyInput(_ctx: RunContext, input: SelectQueueTaskInput): Record<string, unknown> {
+    const incident = this.resolveIncident(_ctx, input);
+    const severityOverride = this.resolveSeverityOverride(_ctx, input);
+    return {
+      action: 'select_queue',
+      incidentId: incident?.id ?? input.incidentId,
+      severityOverride,
+    };
+  }
+
+  verification(): string[] {
+    return ['typeof output.queue === "string"', 'output.rule !== undefined'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: SelectQueueTaskInput
+  ): Promise<SelectQueueOutput> {
+    const tool = ctx.getTool('select_queue');
+    if (!tool) {
+      throw new Error('select_queue tool is not registered');
+    }
+
+    const incident = this.resolveIncident(ctx, input);
+    if (!incident) {
+      throw new Error('incident is required');
+    }
+
+    const severityOverride = this.resolveSeverityOverride(ctx, input);
+    const result = (await tool.call({ incident, severityOverride })) as SelectQueueOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'incident_queue_selected',
+      incidentId: incident.id,
+      queue: result.queue,
+      escalationRequired: result.escalationRequired,
+    });
+    return result;
+  }
+
+  private resolveIncident(
+    ctx: RunContext,
+    input: SelectQueueTaskInput
+  ): IncidentRecord | undefined {
+    if (input?.incident) {
+      return input.incident;
+    }
+
+    const fetchOutput = ctx.outputs?.['task-incident-fetch'] as FetchIncidentOutput | undefined;
+    const incident = fetchOutput?.incident;
+    if (!incident) {
+      return undefined;
+    }
+
+    if (!input?.incidentId || incident.id === input.incidentId) {
+      return incident;
+    }
+
+    return undefined;
+  }
+
+  private resolveSeverityOverride(
+    ctx: RunContext,
+    input: SelectQueueTaskInput
+  ): IncidentSeverity | undefined {
+    if (input?.severityOverride) {
+      return input.severityOverride;
+    }
+
+    const classifyOutput = ctx.outputs?.['task-incident-classify'] as ClassifySeverityOutput | undefined;
+    return classifyOutput?.severity;
+  }
+}
+
+export class EscalateIncidentTask extends Task<
+  EscalateIncidentInput,
+  EscalateIncidentOutput
+> {
+  constructor() {
+    super('task-incident-escalate', 'incident.escalate');
+  }
+
+  policyInput(_ctx: RunContext, input: EscalateIncidentInput): Record<string, unknown> {
+    const resolved = this.resolveEscalationInput(_ctx, input);
+    return {
+      action: 'escalate_incident',
+      incidentId: resolved.incidentId,
+      target: resolved.target,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.escalated === true', 'typeof output.ticketId === "string"'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: EscalateIncidentInput
+  ): Promise<EscalateIncidentOutput> {
+    const tool = ctx.getTool('escalate_incident');
+    if (!tool) {
+      throw new Error('escalate_incident tool is not registered');
+    }
+
+    const resolved = this.resolveEscalationInput(ctx, input);
+    const result = (await tool.call(resolved)) as EscalateIncidentOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'incident_escalated',
+      incidentId: resolved.incidentId,
+      target: result.target,
+      ticketId: result.ticketId,
+    });
+    return result;
+  }
+
+  private resolveEscalationInput(
+    ctx: RunContext,
+    input: EscalateIncidentInput
+  ): EscalateIncidentInput {
+    const fetchOutput = ctx.outputs?.['task-incident-fetch'] as FetchIncidentOutput | undefined;
+    const selectOutput = ctx.outputs?.['task-incident-route'] as SelectQueueOutput | undefined;
+
+    const incidentId = input?.incidentId ?? fetchOutput?.incident?.id;
+    const target = input?.target ?? selectOutput?.rule?.escalatesTo ?? 'incident-manager@northwind.example';
+    const reason =
+      input?.reason ??
+      (selectOutput?.rationale?.join(' ') || 'Escalation triggered by routing decision.');
+
+    if (!incidentId) {
+      throw new Error('incidentId is required for escalation');
+    }
+
+    if (!target) {
+      throw new Error('Escalation target could not be determined');
+    }
+
+    return {
+      incidentId,
+      target,
+      reason,
+    };
+  }
+}

package/src/tasks/index.ts

@@ -0,0 +1,6 @@
+export * from './legacy.js';
+export * from './entitlement.js';
+export * from './knowledge.js';
+export * from './incidents.js';
+export * from './invoices.js';
+export * from './coaching.js';