@deliverd/sdk 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/types.ts CHANGED
@@ -679,7 +679,13 @@ export type WebhookEventName =
679
679
  | "gate.expired"
680
680
  | "gate.cancelled"
681
681
  | "gate.revoked"
682
- | "gate.executed";
682
+ | "gate.executed"
683
+ /** An objective finished. */
684
+ | "task.completed"
685
+ /** Opt-in: a task moved into blocked, or a side task finished and its
686
+ * result waits to be applied, kept or discarded. */
687
+ | "task.blocked"
688
+ | "side_task.completed";
683
689
 
684
690
  export interface WebhookEvent {
685
691
  event: WebhookEventName;
@@ -996,6 +1002,397 @@ export interface ListFlowsInput {
996
1002
  cursor?: string;
997
1003
  }
998
1004
 
1005
+ /* ── Tasks ────────────────────────────────────────────────────────────────── */
1006
+
1007
+ /*
1008
+ * Task Graph: an objective kept apart from the conversation doing the work,
1009
+ * the side tasks branched out of it, and the findings each one produced.
1010
+ *
1011
+ * Every nested shape is named rather than written inline, so the Python SDK
1012
+ * can carry the same class under the same name and the parity guard can hold
1013
+ * the two to each other field by field.
1014
+ */
1015
+
1016
+ export type TaskKind = "objective" | "side_task" | "investigation" | "research" | "debug" | "decision";
1017
+ export type SideTaskKind = "side_task" | "investigation" | "research" | "debug" | "decision";
1018
+ export type TaskStatus = "open" | "in_progress" | "blocked" | "awaiting_approval" | "completed" | "cancelled";
1019
+ /** The statuses `update()` may set. Completing and cancelling have their own calls. */
1020
+ export type SettableTaskStatus = "open" | "in_progress" | "blocked" | "awaiting_approval";
1021
+ /** What became of a finished side task's result: carried into the parent, kept for reference, or not used. */
1022
+ export type TaskOutcome = "applied" | "kept" | "discarded";
1023
+ export type FindingKind =
1024
+ | "hypothesis"
1025
+ | "test"
1026
+ | "evidence"
1027
+ | "finding"
1028
+ | "conclusion"
1029
+ | "recommendation"
1030
+ | "decision"
1031
+ | "risk"
1032
+ | "question"
1033
+ | "action";
1034
+ /** A decision is a suggestion until a person confirms it. */
1035
+ export type DecisionStatus = "suggested" | "confirmed" | "rejected";
1036
+ export type TaskLinkKind = "depends_on" | "blocks" | "related_to" | "supersedes" | "resulted_in";
1037
+
1038
+ /** The short working state of a task: where it stands, what is open, what is in the way, what comes next. */
1039
+ export interface TaskState {
1040
+ currentState: string | null;
1041
+ openQuestions: string[];
1042
+ constraints: string[];
1043
+ blockedBy: string[];
1044
+ nextAction: string | null;
1045
+ }
1046
+
1047
+ /**
1048
+ * A change to a task's state. Fields left out stay as they were; a list sent
1049
+ * replaces the list; `addOpenQuestions` and `resolveOpenQuestions` change it
1050
+ * item by item, so two writers do not have to agree on the whole list.
1051
+ */
1052
+ export interface TaskStatePatch {
1053
+ currentState?: string | null;
1054
+ openQuestions?: string[];
1055
+ addOpenQuestions?: string[];
1056
+ resolveOpenQuestions?: string[];
1057
+ constraints?: string[];
1058
+ blockedBy?: string[];
1059
+ nextAction?: string | null;
1060
+ }
1061
+
1062
+ /** What a side task was given when it began. Not a transcript: the facts it needs. */
1063
+ export interface TaskSnapshot {
1064
+ rootObjective: string;
1065
+ parentObjective: string;
1066
+ sideTaskGoal: string;
1067
+ relevantContext: string[];
1068
+ knownConstraints: string[];
1069
+ relatedDecisions: string[];
1070
+ /** The parent's open question this side task was opened to answer, if any. */
1071
+ resolvesQuestion: string | null;
1072
+ }
1073
+
1074
+ export interface TaskResultFinding {
1075
+ title: string;
1076
+ description: string;
1077
+ evidence?: string[];
1078
+ }
1079
+
1080
+ export interface TaskResultDecision {
1081
+ title: string;
1082
+ rationale?: string;
1083
+ }
1084
+
1085
+ /** What a side task came back with. Structured, so the parent can use it. */
1086
+ export interface TaskResult {
1087
+ summary: string;
1088
+ findings: TaskResultFinding[];
1089
+ decisions: TaskResultDecision[];
1090
+ recommendations: string[];
1091
+ unresolvedQuestions: string[];
1092
+ parentImpact: string | null;
1093
+ suggestedNextAction: string | null;
1094
+ }
1095
+
1096
+ /** An objective's side tasks, counted. On a list only. */
1097
+ export interface SideTaskCounts {
1098
+ open: number;
1099
+ done: number;
1100
+ /** Finished and waiting for somebody to apply, keep or discard the result. */
1101
+ awaiting: number;
1102
+ }
1103
+
1104
+ /** One step from the objective down to a task. */
1105
+ export interface TaskPathEntry {
1106
+ id: string;
1107
+ title: string;
1108
+ kind: TaskKind;
1109
+ }
1110
+
1111
+ export interface TaskLink {
1112
+ sourceTaskId: string;
1113
+ targetTaskId: string;
1114
+ kind: TaskLinkKind;
1115
+ }
1116
+
1117
+ /** A task as the tree shows it: no state, no snapshot, one line of the result. */
1118
+ export interface TaskNode {
1119
+ id: string;
1120
+ parentTaskId: string | null;
1121
+ kind: TaskKind;
1122
+ depth: number;
1123
+ status: TaskStatus;
1124
+ title: string;
1125
+ outcome: TaskOutcome | null;
1126
+ resultSummary: string | null;
1127
+ url: string;
1128
+ }
1129
+
1130
+ /** An inspectable work product: what was tested, seen or concluded. Never private reasoning. */
1131
+ export interface TaskFinding {
1132
+ id: string;
1133
+ taskId: string;
1134
+ kind: FindingKind;
1135
+ title: string;
1136
+ body: string;
1137
+ evidence: string[];
1138
+ /** For a decision: suggested, confirmed or rejected, with any approval taken into account. */
1139
+ decisionStatus: DecisionStatus | null;
1140
+ decidedBy: string | null;
1141
+ decidedAt: string | null;
1142
+ approvalId: string | null;
1143
+ /** The approval's own status, when a decision was put to one. */
1144
+ approvalStatus: string | null;
1145
+ /** The side task it came from, when it arrived with an applied result. */
1146
+ sourceTaskId: string | null;
1147
+ createdBy: string;
1148
+ createdAt: string;
1149
+ }
1150
+
1151
+ export interface TaskData {
1152
+ id: string;
1153
+ kind: TaskKind;
1154
+ status: TaskStatus;
1155
+ /** The page a person can open. */
1156
+ url: string;
1157
+ title: string;
1158
+ /** What the work is for: the objective's purpose, or a side task's goal. */
1159
+ objective: string;
1160
+ rootTaskId: string;
1161
+ /** Null on the objective itself. */
1162
+ parentTaskId: string | null;
1163
+ depth: number;
1164
+ workspaceId: string | null;
1165
+ flowId: string | null;
1166
+ state: TaskState;
1167
+ /** For a side task: what it was given when it began. */
1168
+ snapshot: TaskSnapshot | null;
1169
+ /** Once completed: what it came back with. */
1170
+ result: TaskResult | null;
1171
+ /** Earlier results, kept when a completed task is reopened. */
1172
+ previousResults: TaskResult[];
1173
+ outcome: TaskOutcome | null;
1174
+ origin: "manual" | "suggested";
1175
+ externalId: string | null;
1176
+ sessionUrl: string | null;
1177
+ /** Pass it back as `expectedVersion` to refuse an update somebody else got in before. */
1178
+ version: number;
1179
+ startedBy: string;
1180
+ createdAt: string;
1181
+ updatedAt: string;
1182
+ completedAt: string | null;
1183
+ /** On a list only. */
1184
+ sideTasks?: SideTaskCounts;
1185
+ /** On a single read: from the objective down to this task. */
1186
+ path?: TaskPathEntry[];
1187
+ /** On a single read: the side tasks directly under this one. */
1188
+ children?: TaskNode[];
1189
+ /** On a single read. */
1190
+ findings?: TaskFinding[];
1191
+ /** On a single read. */
1192
+ links?: TaskLink[];
1193
+ /** On create only: true when an open objective with this `externalId` was returned instead of a new one. */
1194
+ resumed?: boolean;
1195
+ }
1196
+
1197
+ export interface TaskContextTask {
1198
+ id: string;
1199
+ kind: TaskKind;
1200
+ title: string;
1201
+ objective: string;
1202
+ status: TaskStatus;
1203
+ isSideTask: boolean;
1204
+ }
1205
+
1206
+ export interface TaskContextDecisions {
1207
+ confirmed: string[];
1208
+ suggested: string[];
1209
+ }
1210
+
1211
+ export interface TaskContextFinding {
1212
+ kind: FindingKind;
1213
+ title: string;
1214
+ body: string;
1215
+ }
1216
+
1217
+ export interface ActiveSideTask {
1218
+ id: string;
1219
+ title: string;
1220
+ kind: TaskKind;
1221
+ status: TaskStatus;
1222
+ }
1223
+
1224
+ /** Finished, and waiting for somebody to apply, keep or discard the result. */
1225
+ export interface AwaitingSideTask {
1226
+ id: string;
1227
+ title: string;
1228
+ summary: string | null;
1229
+ }
1230
+
1231
+ export interface CompletedSideTask {
1232
+ id: string;
1233
+ title: string;
1234
+ summary: string | null;
1235
+ outcome: TaskOutcome | null;
1236
+ }
1237
+
1238
+ export interface TaskContextSideTasks {
1239
+ active: ActiveSideTask[];
1240
+ awaitingOutcome: AwaitingSideTask[];
1241
+ completed: CompletedSideTask[];
1242
+ }
1243
+
1244
+ /**
1245
+ * What an agent reads instead of the history: the objective first, always,
1246
+ * then where this task stands and what is settled. Small on purpose.
1247
+ */
1248
+ export interface TaskContext {
1249
+ rootObjective: string;
1250
+ task: TaskContextTask;
1251
+ path: TaskPathEntry[];
1252
+ currentState: string | null;
1253
+ nextAction: string | null;
1254
+ openQuestions: string[];
1255
+ constraints: string[];
1256
+ blockedBy: string[];
1257
+ decisions: TaskContextDecisions;
1258
+ snapshot: TaskSnapshot | null;
1259
+ relevantFindings: TaskContextFinding[];
1260
+ sideTasks: TaskContextSideTasks;
1261
+ /** One paragraph to say back to yourself to re-anchor on the objective. */
1262
+ reanchor: string;
1263
+ }
1264
+
1265
+ export interface TaskGraph {
1266
+ root: TaskData;
1267
+ nodes: TaskNode[];
1268
+ links: TaskLink[];
1269
+ }
1270
+
1271
+ /** What applying a side task's result did: both tasks as they now are, and the parent's fresh context. */
1272
+ export interface AppliedSideTask {
1273
+ sideTask: TaskData;
1274
+ parent: TaskData;
1275
+ message: string;
1276
+ context: TaskContext;
1277
+ }
1278
+
1279
+ export interface DecisionApproval {
1280
+ finding: TaskFinding;
1281
+ approvalId: string;
1282
+ approvalUrl: string;
1283
+ }
1284
+
1285
+ export interface TaskLinkResult {
1286
+ linked: boolean;
1287
+ sourceTaskId: string;
1288
+ targetTaskId: string;
1289
+ kind: TaskLinkKind;
1290
+ /** False when the link already existed. */
1291
+ created: boolean;
1292
+ }
1293
+
1294
+ export interface CreateTaskInput {
1295
+ /** A short name for the objective. */
1296
+ title: string;
1297
+ /** What the work is ultimately for. Returned at the top of every context. */
1298
+ objective: string;
1299
+ workspaceId?: string;
1300
+ /** The flow its approvals and reviews belong to. */
1301
+ flowId?: string;
1302
+ /** Your own reference. An open objective you started under it is returned instead of a new one. */
1303
+ externalId?: string;
1304
+ /** A link to the conversation where the work happens. */
1305
+ sessionUrl?: string;
1306
+ /** The starting state, if anything is already known. */
1307
+ state?: TaskStatePatch;
1308
+ }
1309
+
1310
+ export interface ListTasksInput {
1311
+ /** A status, or `active` for anything not completed or cancelled. */
1312
+ status?: TaskStatus | "active";
1313
+ externalId?: string;
1314
+ /** Search the titles and objectives. */
1315
+ q?: string;
1316
+ /** One page of this size. Leave it unset to get every row. */
1317
+ limit?: number;
1318
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
1319
+ cursor?: string;
1320
+ }
1321
+
1322
+ export interface UpdateTaskInput {
1323
+ title?: string;
1324
+ /** Refused to an agent: only a person changes what the work is for. Propose it as a finding. */
1325
+ objective?: string;
1326
+ status?: SettableTaskStatus;
1327
+ sessionUrl?: string | null;
1328
+ state?: TaskStatePatch;
1329
+ /** The version you read; the update is refused if somebody wrote in between. */
1330
+ expectedVersion?: number;
1331
+ }
1332
+
1333
+ export interface CreateSideTaskInput {
1334
+ title: string;
1335
+ /** What exactly it has to solve. Narrow is better: it is done when this is answered. */
1336
+ goal: string;
1337
+ kind?: SideTaskKind;
1338
+ /** The context it needs, replacing what Deliverd would select from the parent. */
1339
+ relevantContext?: string[];
1340
+ /** What it must respect; the parent's constraints when omitted. */
1341
+ knownConstraints?: string[];
1342
+ /** One of the parent's open questions; it comes off the list when the result is applied. */
1343
+ resolvesQuestion?: string;
1344
+ /** `suggested` when you proposed the side task and the person agreed. */
1345
+ origin?: "manual" | "suggested";
1346
+ sessionUrl?: string;
1347
+ }
1348
+
1349
+ export interface AddFindingInput {
1350
+ /** A `decision` is recorded as a suggestion until a person confirms it. */
1351
+ kind: FindingKind;
1352
+ title: string;
1353
+ /** The substance, written for a person: what you tested, saw or concluded. */
1354
+ body?: string;
1355
+ /** Short pieces of evidence: a log line, a value, a measurement. */
1356
+ evidence?: string[];
1357
+ }
1358
+
1359
+ export interface CompleteTaskInput {
1360
+ /** What was found, in a few sentences. */
1361
+ summary: string;
1362
+ findings?: TaskResultFinding[];
1363
+ /** Decisions you propose. They reach the parent as suggestions. */
1364
+ decisions?: TaskResultDecision[];
1365
+ recommendations?: string[];
1366
+ /** Added to the parent's open questions when applied. */
1367
+ unresolvedQuestions?: string[];
1368
+ /** What this means for the main task. */
1369
+ parentImpact?: string;
1370
+ /** Becomes the parent's next action when applied. */
1371
+ suggestedNextAction?: string;
1372
+ }
1373
+
1374
+ export interface ApplySideTaskInput {
1375
+ /** `applied` (the default) carries the result into the parent; `kept` records it as reference; `discarded` records it was not used. */
1376
+ outcome?: TaskOutcome;
1377
+ }
1378
+
1379
+ export interface CancelTaskInput {
1380
+ /** Why it was called off, for whoever reads the history. */
1381
+ reason?: string;
1382
+ }
1383
+
1384
+ export interface RequestDecisionApprovalInput {
1385
+ /** Emails, names or groups; the organisation's administrators when omitted. */
1386
+ approvers?: string[];
1387
+ note?: string;
1388
+ expiresAt?: string;
1389
+ }
1390
+
1391
+ export interface LinkTasksInput {
1392
+ targetTaskId: string;
1393
+ kind: TaskLinkKind;
1394
+ }
1395
+
999
1396
  /* ── Evidence ─────────────────────────────────────────────────────────────── */
1000
1397
 
1001
1398
  export type EvidenceStepKind = "approval" | "review" | "collection" | "report";