@gadicc/loom 1.18.0 → 1.20.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.
Files changed (65) hide show
  1. package/README.md +70 -5
  2. package/THIRD_PARTY_NOTICES.md +11 -10
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +18 -0
  5. package/esm/src/cli/mod.d.ts.map +1 -1
  6. package/esm/src/cli/mod.js +16 -1
  7. package/esm/src/jobs/controller.d.ts +14 -1
  8. package/esm/src/jobs/controller.d.ts.map +1 -1
  9. package/esm/src/jobs/controller.js +54 -3
  10. package/esm/src/jobs/events.d.ts +9 -1
  11. package/esm/src/jobs/events.d.ts.map +1 -1
  12. package/esm/src/jobs/events.js +15 -2
  13. package/esm/src/jobs/mod.d.ts +1 -0
  14. package/esm/src/jobs/mod.d.ts.map +1 -1
  15. package/esm/src/jobs/mod.js +1 -0
  16. package/esm/src/jobs/run.d.ts +20 -1
  17. package/esm/src/jobs/run.d.ts.map +1 -1
  18. package/esm/src/jobs/run.js +29 -4
  19. package/esm/src/jobs/sanitize.d.ts +30 -0
  20. package/esm/src/jobs/sanitize.d.ts.map +1 -0
  21. package/esm/src/jobs/sanitize.js +91 -0
  22. package/esm/src/mail/postal.d.ts.map +1 -1
  23. package/esm/src/mail/postal.js +25 -20
  24. package/esm/src/mail/sender.d.ts +5 -0
  25. package/esm/src/mail/sender.d.ts.map +1 -0
  26. package/esm/src/mail/sender.js +48 -0
  27. package/esm/src/mail/service.d.ts.map +1 -1
  28. package/esm/src/mail/service.js +7 -5
  29. package/esm/src/next/jobs/route.d.ts.map +1 -1
  30. package/esm/src/next/jobs/route.js +1 -1
  31. package/package.json +2 -2
  32. package/script/src/cli/externalSkills.d.ts.map +1 -1
  33. package/script/src/cli/externalSkills.js +18 -0
  34. package/script/src/cli/mod.d.ts.map +1 -1
  35. package/script/src/cli/mod.js +16 -1
  36. package/script/src/jobs/controller.d.ts +14 -1
  37. package/script/src/jobs/controller.d.ts.map +1 -1
  38. package/script/src/jobs/controller.js +54 -3
  39. package/script/src/jobs/events.d.ts +9 -1
  40. package/script/src/jobs/events.d.ts.map +1 -1
  41. package/script/src/jobs/events.js +15 -2
  42. package/script/src/jobs/mod.d.ts +1 -0
  43. package/script/src/jobs/mod.d.ts.map +1 -1
  44. package/script/src/jobs/mod.js +1 -0
  45. package/script/src/jobs/run.d.ts +20 -1
  46. package/script/src/jobs/run.d.ts.map +1 -1
  47. package/script/src/jobs/run.js +29 -4
  48. package/script/src/jobs/sanitize.d.ts +30 -0
  49. package/script/src/jobs/sanitize.d.ts.map +1 -0
  50. package/script/src/jobs/sanitize.js +97 -0
  51. package/script/src/mail/postal.d.ts.map +1 -1
  52. package/script/src/mail/postal.js +25 -20
  53. package/script/src/mail/sender.d.ts +5 -0
  54. package/script/src/mail/sender.d.ts.map +1 -0
  55. package/script/src/mail/sender.js +52 -0
  56. package/script/src/mail/service.d.ts.map +1 -1
  57. package/script/src/mail/service.js +7 -5
  58. package/script/src/next/jobs/route.d.ts.map +1 -1
  59. package/script/src/next/jobs/route.js +1 -1
  60. package/skills/loom/SKILL.md +14 -1
  61. package/skills/loom-jobs/SKILL.md +27 -0
  62. package/skills/loom-mail/SKILL.md +14 -3
  63. package/skills/loom-torvalds-review/SKILL.md +116 -0
  64. package/skills/loom-torvalds-review/agents/openai.yaml +4 -0
  65. package/skills/loom-torvalds-review/references/context-profiles.md +156 -0
@@ -1,3 +1,4 @@
1
+ import { type JobOutputSanitizer } from "./sanitize.js";
1
2
  export declare const JOB_LOG_LEVELS: readonly ["fatal", "error", "warn", "info", "log", "debug", "trace"];
2
3
  export type JobLogLevel = (typeof JOB_LOG_LEVELS)[number];
3
4
  export declare const JOB_LOG_LEVEL_TO_INT: Readonly<Record<JobLogLevel, number>>;
@@ -8,7 +9,14 @@ export interface JobLogEvent {
8
9
  _log: [timestamp: number, levelInt: number, ...args: unknown[]];
9
10
  }
10
11
  export type JobStreamEvent = JobLifecycleEvent | JobLogEvent | Record<string, unknown>;
11
- export declare function serializeJobEvent(event: JobStreamEvent): string;
12
+ /**
13
+ * Serialize one job event, optionally sanitizing every string value.
14
+ *
15
+ * JSON's replacer traversal preserves its normal handling of arrays, objects,
16
+ * dates, primitives, `toJSON`, omitted object values, and array holes without
17
+ * mutating the input value.
18
+ */
19
+ export declare function serializeJobEvent(event: unknown, outputSanitizer?: JobOutputSanitizer): string;
12
20
  export declare function parseJobEvent(line: string): JobStreamEvent;
13
21
  export declare function isJobLifecycleEvent(event: JobStreamEvent): event is JobLifecycleEvent;
14
22
  export declare function isJobLogEvent(event: JobStreamEvent): event is JobLogEvent;
@@ -1 +1 @@
1
- {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/events.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,sEAQjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAQtE,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,WAAW,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAE/D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,GACpB,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,WAAW,CAEzE"}
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/events.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,cAAc,sEAQjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAQtE,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,WAAW,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,eAAe,CAAC,EAAE,kBAAkB,GACnC,MAAM,CAWR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,GACpB,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,WAAW,CAEzE"}
@@ -5,6 +5,7 @@ exports.serializeJobEvent = serializeJobEvent;
5
5
  exports.parseJobEvent = parseJobEvent;
6
6
  exports.isJobLifecycleEvent = isJobLifecycleEvent;
7
7
  exports.isJobLogEvent = isJobLogEvent;
8
+ const sanitize_js_1 = require("./sanitize.js");
8
9
  exports.JOB_LOG_LEVELS = [
9
10
  "fatal",
10
11
  "error",
@@ -23,8 +24,20 @@ exports.JOB_LOG_LEVEL_TO_INT = {
23
24
  debug: 5,
24
25
  trace: 6,
25
26
  };
26
- function serializeJobEvent(event) {
27
- return `${JSON.stringify(event)}\n`;
27
+ /**
28
+ * Serialize one job event, optionally sanitizing every string value.
29
+ *
30
+ * JSON's replacer traversal preserves its normal handling of arrays, objects,
31
+ * dates, primitives, `toJSON`, omitted object values, and array holes without
32
+ * mutating the input value.
33
+ */
34
+ function serializeJobEvent(event, outputSanitizer) {
35
+ const serialized = outputSanitizer
36
+ ? JSON.stringify(event, (_key, value) => typeof value === "string"
37
+ ? (0, sanitize_js_1.sanitizeJobOutputString)(outputSanitizer, value)
38
+ : value)
39
+ : JSON.stringify(event);
40
+ return `${serialized}\n`;
28
41
  }
29
42
  function parseJobEvent(line) {
30
43
  return JSON.parse(line);
@@ -6,5 +6,6 @@ export * from "./format.js";
6
6
  export * from "./http.js";
7
7
  export * from "./log.js";
8
8
  export * from "./run.js";
9
+ export * from "./sanitize.js";
9
10
  export * from "./types.js";
10
11
  //# sourceMappingURL=mod.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/mod.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/mod.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}
@@ -22,4 +22,5 @@ __exportStar(require("./format.js"), exports);
22
22
  __exportStar(require("./http.js"), exports);
23
23
  __exportStar(require("./log.js"), exports);
24
24
  __exportStar(require("./run.js"), exports);
25
+ __exportStar(require("./sanitize.js"), exports);
25
26
  __exportStar(require("./types.js"), exports);
@@ -1,7 +1,10 @@
1
- import { JobController } from "./controller.js";
1
+ import { type DeferredTaskErrorHandler, JobController } from "./controller.js";
2
+ import { type JobOutputSanitizer } from "./sanitize.js";
2
3
  import type { JobDefinition, JobParams } from "./types.js";
3
4
  export interface JobRunResult<TJob extends JobDefinition = JobDefinition> {
4
5
  controller: JobController;
6
+ /** Present on Loom-created executions; optional for legacy result adapters. */
7
+ deferredTaskFailureCount?: number;
5
8
  error: unknown | null;
6
9
  job: TJob;
7
10
  params: JobParams;
@@ -12,8 +15,24 @@ export interface JobExecution<TJob extends JobDefinition = JobDefinition> {
12
15
  getController: () => JobController | null;
13
16
  }
14
17
  export interface CreateJobExecutionOptions {
18
+ /**
19
+ * Message deliberately emitted when the job handler throws. Omit it to keep
20
+ * Loom's legacy full-stack output behavior.
21
+ */
22
+ handlerErrorMessage?: string;
23
+ /** Maximum log level included in the event stream. */
15
24
  maxLogLevel?: number;
25
+ /** Sanitize every string value emitted through the job controller. */
26
+ outputSanitizer?: JobOutputSanitizer;
27
+ /** Run deferred tasks before the end event instead of leaving them pending. */
16
28
  runDeferredTasks?: boolean;
29
+ /** Handle deferred-task errors independently from handler error disclosure. */
30
+ deferredTaskErrorHandler?: DeferredTaskErrorHandler;
31
+ /**
32
+ * Message emitted when a consumer cancels the stream. Set to `false` to keep
33
+ * cancellation silent. Omit it to preserve the legacy "Job cancelled" log.
34
+ */
35
+ cancellationMessage?: string | false;
17
36
  }
18
37
  export declare function formatJobError(error: unknown): string;
19
38
  export declare function createJobExecution<TJob extends JobDefinition>(job: TJob, params?: JobParams, options?: CreateJobExecutionOptions): JobExecution<TJob>;
@@ -1 +1 @@
1
- {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACtE,UAAU,EAAE,aAAa,CAAC;IAC1B,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACtE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,aAAa,EAAE,MAAM,aAAa,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,aAAa,EAC3D,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,SAAc,EACtB,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAAC,IAAI,CAAC,CAiDpB"}
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,wBAAwB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACtE,UAAU,EAAE,aAAa,CAAC;IAC1B,+EAA+E;IAC/E,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACtE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,aAAa,EAAE,MAAM,aAAa,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,eAAe,CAAC,EAAE,kBAAkB,CAAC;IACrC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IACpD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACtC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,aAAa,EAC3D,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,SAAc,EACtB,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAAC,IAAI,CAAC,CAgFpB"}
@@ -4,6 +4,7 @@ exports.formatJobError = formatJobError;
4
4
  exports.createJobExecution = createJobExecution;
5
5
  const controller_js_1 = require("./controller.js");
6
6
  const events_js_1 = require("./events.js");
7
+ const sanitize_js_1 = require("./sanitize.js");
7
8
  function formatJobError(error) {
8
9
  if (error instanceof Error) {
9
10
  return error.stack ?? error.toString();
@@ -24,22 +25,44 @@ function createJobExecution(job, params = {}, options = {}) {
24
25
  const stream = new ReadableStream({
25
26
  async start(controller) {
26
27
  controller.enqueue((0, events_js_1.serializeJobEvent)({ _job: "start" }));
27
- jobController = new controller_js_1.JobController(controller, options.maxLogLevel);
28
+ jobController = new controller_js_1.JobController(controller, options.maxLogLevel, options.outputSanitizer);
28
29
  let error = null;
30
+ let deferredTaskFailureCount = 0;
29
31
  try {
30
32
  await job.handler(jobController, params);
33
+ if (jobController._outputSanitationFailed) {
34
+ throw new sanitize_js_1.JobOutputSanitationError();
35
+ }
31
36
  if (options.runDeferredTasks) {
32
- await jobController.runDeferredTasks();
37
+ const deferredResult = await jobController.runDeferredTasksWithResult(options.deferredTaskErrorHandler);
38
+ deferredTaskFailureCount = deferredResult.failureCount;
33
39
  }
34
40
  }
35
41
  catch (caught) {
36
42
  error = caught;
37
- jobController.fatal(formatJobError(caught));
43
+ if (caught instanceof sanitize_js_1.JobOutputSanitationError ||
44
+ jobController._outputSanitationFailed) {
45
+ jobController._emitOutputSanitationFailure();
46
+ }
47
+ else {
48
+ try {
49
+ jobController.fatal(options.handlerErrorMessage ?? formatJobError(caught));
50
+ }
51
+ catch (reportingError) {
52
+ if (reportingError instanceof sanitize_js_1.JobOutputSanitationError) {
53
+ jobController._emitOutputSanitationFailure();
54
+ }
55
+ else {
56
+ throw reportingError;
57
+ }
58
+ }
59
+ }
38
60
  }
39
61
  controller.enqueue((0, events_js_1.serializeJobEvent)({ _job: "end" }));
40
62
  controller.close();
41
63
  resolveResult({
42
64
  controller: jobController,
65
+ deferredTaskFailureCount,
43
66
  error,
44
67
  job,
45
68
  params,
@@ -49,7 +72,9 @@ function createJobExecution(job, params = {}, options = {}) {
49
72
  if (!jobController) {
50
73
  throw new Error("Job cancelled but job controller not set.");
51
74
  }
52
- jobController.log("Job cancelled");
75
+ if (options.cancellationMessage !== false) {
76
+ jobController.log(options.cancellationMessage ?? "Job cancelled");
77
+ }
53
78
  jobController._cancelled = true;
54
79
  },
55
80
  });
@@ -0,0 +1,30 @@
1
+ /** Default literal used when a redaction rule has `true` as its replacement. */
2
+ export declare const DEFAULT_JOB_OUTPUT_REDACTION = "[REDACTED]";
3
+ /** Safe event text emitted when a configured output sanitizer cannot run. */
4
+ export declare const JOB_OUTPUT_SANITATION_FAILURE_MESSAGE = "Job output sanitation failed.";
5
+ /** Transform one string value before it enters a serialized job event. */
6
+ export type JobOutputSanitizer = (value: string) => string;
7
+ /** Ordered exact-string and regular-expression output redaction rules. */
8
+ export type JobOutputRedactionRules = ReadonlyMap<string | RegExp, true | string>;
9
+ /**
10
+ * Fixed, input-independent error raised when output sanitation fails.
11
+ *
12
+ * The original sanitizer error is deliberately not attached because its
13
+ * message or cause may include the value that was being sanitized.
14
+ */
15
+ export declare class JobOutputSanitationError extends Error {
16
+ constructor();
17
+ }
18
+ /**
19
+ * Create a deterministic string redactor from ordered exact and RegExp rules.
20
+ *
21
+ * Rules run in map insertion order and each rule receives the result of the
22
+ * previous rule. Exact strings are replaced everywhere. RegExp rules replace
23
+ * every match regardless of their original `g`, `y`, or `lastIndex` state.
24
+ * Replacement strings are always literal, so `$&`, `$1`, and `$$` have no
25
+ * special meaning. The rules are snapshotted when this function is called.
26
+ */
27
+ export declare function createJobOutputRedactor(rules: JobOutputRedactionRules): JobOutputSanitizer;
28
+ /** @internal Apply a sanitizer while replacing all failures with a safe error. */
29
+ export declare function sanitizeJobOutputString(sanitizer: JobOutputSanitizer, value: string): string;
30
+ //# sourceMappingURL=sanitize.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/sanitize.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,qCAAqC,kCACjB,CAAC;AAElC,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3D,0EAA0E;AAC1E,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAC/C,MAAM,GAAG,MAAM,EACf,IAAI,GAAG,MAAM,CACd,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;;CAKlD;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CA+DpB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM,CAUR"}
@@ -0,0 +1,97 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.JobOutputSanitationError = exports.JOB_OUTPUT_SANITATION_FAILURE_MESSAGE = exports.DEFAULT_JOB_OUTPUT_REDACTION = void 0;
4
+ exports.createJobOutputRedactor = createJobOutputRedactor;
5
+ exports.sanitizeJobOutputString = sanitizeJobOutputString;
6
+ /** Default literal used when a redaction rule has `true` as its replacement. */
7
+ exports.DEFAULT_JOB_OUTPUT_REDACTION = "[REDACTED]";
8
+ /** Safe event text emitted when a configured output sanitizer cannot run. */
9
+ exports.JOB_OUTPUT_SANITATION_FAILURE_MESSAGE = "Job output sanitation failed.";
10
+ /**
11
+ * Fixed, input-independent error raised when output sanitation fails.
12
+ *
13
+ * The original sanitizer error is deliberately not attached because its
14
+ * message or cause may include the value that was being sanitized.
15
+ */
16
+ class JobOutputSanitationError extends Error {
17
+ constructor() {
18
+ super(exports.JOB_OUTPUT_SANITATION_FAILURE_MESSAGE);
19
+ this.name = "JobOutputSanitationError";
20
+ }
21
+ }
22
+ exports.JobOutputSanitationError = JobOutputSanitationError;
23
+ function compileRegExpFlags(flags) {
24
+ // A redaction rule always scans the full string. `lastIndex`, `g`, and `y`
25
+ // therefore cannot make matching depend on prior calls or an initial offset.
26
+ return `${flags.replaceAll("g", "").replaceAll("y", "")}g`;
27
+ }
28
+ /**
29
+ * Create a deterministic string redactor from ordered exact and RegExp rules.
30
+ *
31
+ * Rules run in map insertion order and each rule receives the result of the
32
+ * previous rule. Exact strings are replaced everywhere. RegExp rules replace
33
+ * every match regardless of their original `g`, `y`, or `lastIndex` state.
34
+ * Replacement strings are always literal, so `$&`, `$1`, and `$$` have no
35
+ * special meaning. The rules are snapshotted when this function is called.
36
+ */
37
+ function createJobOutputRedactor(rules) {
38
+ const compiled = [];
39
+ let index = 0;
40
+ for (const [matcher, configuredReplacement] of rules) {
41
+ index++;
42
+ const replacement = configuredReplacement === true
43
+ ? exports.DEFAULT_JOB_OUTPUT_REDACTION
44
+ : configuredReplacement;
45
+ if (typeof replacement !== "string") {
46
+ throw new TypeError(`Job output redaction rule ${index} has an invalid replacement.`);
47
+ }
48
+ if (typeof matcher === "string") {
49
+ if (matcher.length === 0) {
50
+ throw new TypeError(`Job output redaction rule ${index} has an empty exact-string matcher.`);
51
+ }
52
+ compiled.push({ kind: "exact", replacement, search: matcher });
53
+ continue;
54
+ }
55
+ if (!(matcher instanceof RegExp)) {
56
+ throw new TypeError(`Job output redaction rule ${index} has an invalid matcher.`);
57
+ }
58
+ try {
59
+ compiled.push({
60
+ flags: compileRegExpFlags(matcher.flags),
61
+ kind: "regexp",
62
+ replacement,
63
+ source: matcher.source,
64
+ });
65
+ }
66
+ catch {
67
+ throw new TypeError(`Job output redaction rule ${index} has an invalid regular expression.`);
68
+ }
69
+ }
70
+ return (value) => {
71
+ let sanitized = value;
72
+ for (const rule of compiled) {
73
+ if (rule.kind === "exact") {
74
+ sanitized = sanitized.split(rule.search).join(rule.replacement);
75
+ continue;
76
+ }
77
+ // Create a fresh matcher per application so no RegExp state can cross
78
+ // values, rules, executions, or concurrent consumers.
79
+ const matcher = new RegExp(rule.source, rule.flags);
80
+ sanitized = sanitized.replace(matcher, () => rule.replacement);
81
+ }
82
+ return sanitized;
83
+ };
84
+ }
85
+ /** @internal Apply a sanitizer while replacing all failures with a safe error. */
86
+ function sanitizeJobOutputString(sanitizer, value) {
87
+ try {
88
+ const sanitized = sanitizer(value);
89
+ if (typeof sanitized !== "string") {
90
+ throw new JobOutputSanitationError();
91
+ }
92
+ return sanitized;
93
+ }
94
+ catch {
95
+ throw new JobOutputSanitationError();
96
+ }
97
+ }
@@ -1 +1 @@
1
- {"version":3,"file":"postal.d.ts","sourceRoot":"","sources":["../../../src/src/mail/postal.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAA0B,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAEV,qBAAqB,EACrB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CACf,MAAM,EACN;YAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CACjE,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAKxE;AAuDD,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,iBAAiB,CA+EnB;AAoBD,0EAA0E;AAC1E,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC/C;;GAsDA;AA2DD,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA0BtE"}
1
+ {"version":3,"file":"postal.d.ts","sourceRoot":"","sources":["../../../src/src/mail/postal.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAA0B,MAAM,aAAa,CAAC;AAKpE,OAAO,KAAK,EAEV,qBAAqB,EACrB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CACf,MAAM,EACN;YAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CACjE,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAKxE;AAyDD,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,iBAAiB,CAgFnB;AAoBD,0EAA0E;AAC1E,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC/C;;GAsDA;AA2DD,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA0BtE"}
@@ -6,6 +6,7 @@ exports.verifyPostalWebhookSignature = verifyPostalWebhookSignature;
6
6
  exports.parsePostalWebhook = parsePostalWebhook;
7
7
  require("../../_dnt.polyfills.js");
8
8
  const errors_js_1 = require("./errors.js");
9
+ const sender_js_1 = require("./sender.js");
9
10
  class LoomPostalWebhookError extends errors_js_1.LoomMailError {
10
11
  constructor(message, options) {
11
12
  super(message, { code: options.code });
@@ -33,9 +34,12 @@ function postalBaseUrl(host) {
33
34
  : `https://${normalized}`;
34
35
  }
35
36
  function fromAddress(message) {
36
- return message.fromName
37
- ? `${message.fromName} <${message.fromEmail}>`
38
- : message.fromEmail;
37
+ const email = (0, sender_js_1.normalizeLoomMailFromEmail)(message.fromEmail);
38
+ const name = (0, sender_js_1.normalizeLoomMailFromName)(message.fromName);
39
+ if (!name)
40
+ return email;
41
+ const quotedName = name.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
42
+ return `"${quotedName}" <${email}>`;
39
43
  }
40
44
  function retryableHttpStatus(status) {
41
45
  return status === 408 || status === 429 || status >= 500;
@@ -74,26 +78,27 @@ function createPostalMailTransport(options) {
74
78
  if (!options.apiKey.trim()) {
75
79
  throw new errors_js_1.LoomMailTransportError("Postal API key is not configured.", { code: "postal_not_configured", retryable: false });
76
80
  }
81
+ const requestBody = {
82
+ attachments: message.attachments.map((attachment) => ({
83
+ content_type: attachment.contentType ?? undefined,
84
+ data: attachment.data,
85
+ name: attachment.name,
86
+ })),
87
+ bcc: message.bcc,
88
+ cc: message.cc,
89
+ from: fromAddress(message),
90
+ headers: message.headers,
91
+ html_body: message.htmlBody ?? undefined,
92
+ plain_body: message.plainBody ?? undefined,
93
+ reply_to: message.replyTo ?? undefined,
94
+ subject: message.subject,
95
+ tag: message.tag ?? undefined,
96
+ to: message.to,
97
+ };
77
98
  let response;
78
99
  try {
79
100
  response = await fetchImpl(new URL("/api/v1/send/message", postalBaseUrl(options.host)), {
80
- body: JSON.stringify({
81
- attachments: message.attachments.map((attachment) => ({
82
- content_type: attachment.contentType ?? undefined,
83
- data: attachment.data,
84
- name: attachment.name,
85
- })),
86
- bcc: message.bcc,
87
- cc: message.cc,
88
- from: fromAddress(message),
89
- headers: message.headers,
90
- html_body: message.htmlBody ?? undefined,
91
- plain_body: message.plainBody ?? undefined,
92
- reply_to: message.replyTo ?? undefined,
93
- subject: message.subject,
94
- tag: message.tag ?? undefined,
95
- to: message.to,
96
- }),
101
+ body: JSON.stringify(requestBody),
97
102
  headers: {
98
103
  "Content-Type": "application/json",
99
104
  "X-Server-API-Key": options.apiKey,
@@ -0,0 +1,5 @@
1
+ /** Normalizes a bare sender address without attempting full addr-spec parsing. */
2
+ export declare function normalizeLoomMailFromEmail(value: string): string;
3
+ /** Normalizes an optional sender display name and rejects header controls. */
4
+ export declare function normalizeLoomMailFromName(value?: string | null): string | null;
5
+ //# sourceMappingURL=sender.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../../src/src/mail/sender.ts"],"names":[],"mappings":"AAmCA,kFAAkF;AAClF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,UAYvD;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,iBAK9D"}
@@ -0,0 +1,52 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.normalizeLoomMailFromEmail = normalizeLoomMailFromEmail;
4
+ exports.normalizeLoomMailFromName = normalizeLoomMailFromName;
5
+ const errors_js_1 = require("./errors.js");
6
+ const CONTROL_CHARACTER = /\p{Cc}/u;
7
+ function assertNoHeaderControlCharacters(value, field) {
8
+ if (CONTROL_CHARACTER.test(value)) {
9
+ throw new errors_js_1.LoomMailValidationError(`${field} must not contain control characters.`);
10
+ }
11
+ }
12
+ function hasUnquotedAngleBracket(value) {
13
+ let escaped = false;
14
+ let quoted = false;
15
+ for (const character of value) {
16
+ if (quoted && escaped) {
17
+ escaped = false;
18
+ continue;
19
+ }
20
+ if (quoted && character === "\\") {
21
+ escaped = true;
22
+ continue;
23
+ }
24
+ if (character === '"') {
25
+ quoted = !quoted;
26
+ continue;
27
+ }
28
+ if (!quoted && (character === "<" || character === ">"))
29
+ return true;
30
+ }
31
+ return false;
32
+ }
33
+ /** Normalizes a bare sender address without attempting full addr-spec parsing. */
34
+ function normalizeLoomMailFromEmail(value) {
35
+ assertNoHeaderControlCharacters(value, "fromEmail");
36
+ const normalized = value.trim();
37
+ if (!normalized) {
38
+ throw new errors_js_1.LoomMailValidationError("A From address is required.");
39
+ }
40
+ if (hasUnquotedAngleBracket(normalized)) {
41
+ throw new errors_js_1.LoomMailValidationError("fromEmail must be a bare email address; pass the display name through fromName instead.");
42
+ }
43
+ return normalized;
44
+ }
45
+ /** Normalizes an optional sender display name and rejects header controls. */
46
+ function normalizeLoomMailFromName(value) {
47
+ if (value === undefined || value === null)
48
+ return null;
49
+ assertNoHeaderControlCharacters(value, "fromName");
50
+ const normalized = value.trim();
51
+ return normalized || null;
52
+ }
@@ -1 +1 @@
1
- {"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/src/mail/service.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEV,oBAAoB,EAEpB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,qBAAqB,GAAG,qBAAqB;IAE9D,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,UAAU,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAsCD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,oBAAoB,CA0BtB;AAWD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,SAAS,qBAAqB,GAAG,qBAAqB,EAC9D,OAAO,EAAE,4BAA4B,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CA2H5E"}
1
+ {"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/src/mail/service.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,oBAAoB,EAEpB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,qBAAqB,GAAG,qBAAqB;IAE9D,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,UAAU,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAmCD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,oBAAoB,CA8BtB;AAWD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,SAAS,qBAAqB,GAAG,qBAAqB,EAC9D,OAAO,EAAE,4BAA4B,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CA2H5E"}
@@ -4,6 +4,7 @@ exports.normalizeLoomMailInput = normalizeLoomMailInput;
4
4
  exports.createLoomMailService = createLoomMailService;
5
5
  const errors_js_1 = require("./errors.js");
6
6
  const retry_js_1 = require("./retry.js");
7
+ const sender_js_1 = require("./sender.js");
7
8
  function recipients(value) {
8
9
  if (!value)
9
10
  return [];
@@ -16,9 +17,6 @@ function nullableText(value) {
16
17
  return normalized ? normalized : null;
17
18
  }
18
19
  function assertMailInput(input, normalized) {
19
- if (!normalized.fromEmail) {
20
- throw new errors_js_1.LoomMailValidationError("A From address is required.");
21
- }
22
20
  if (!input.subject.trim()) {
23
21
  throw new errors_js_1.LoomMailValidationError("A subject is required.");
24
22
  }
@@ -30,10 +28,14 @@ function assertMailInput(input, normalized) {
30
28
  }
31
29
  }
32
30
  function normalizeLoomMailInput(input, defaults) {
31
+ const overrideFromEmail = input.fromEmail === undefined
32
+ ? undefined
33
+ : (0, sender_js_1.normalizeLoomMailFromEmail)(input.fromEmail);
33
34
  const normalized = {
34
35
  bcc: recipients(input.bcc),
35
36
  cc: recipients(input.cc),
36
- fromEmail: input.fromEmail?.trim() || defaults.fromEmail.trim(),
37
+ fromEmail: overrideFromEmail ||
38
+ (0, sender_js_1.normalizeLoomMailFromEmail)(defaults.fromEmail),
37
39
  to: recipients(input.to),
38
40
  };
39
41
  assertMailInput(input, normalized);
@@ -44,7 +46,7 @@ function normalizeLoomMailInput(input, defaults) {
44
46
  name: attachment.name,
45
47
  })),
46
48
  ...normalized,
47
- fromName: nullableText(input.fromName ?? defaults.fromName),
49
+ fromName: (0, sender_js_1.normalizeLoomMailFromName)(input.fromName ?? defaults.fromName),
48
50
  headers: { ...input.headers },
49
51
  htmlBody: nullableText(input.htmlBody),
50
52
  metadata: { ...input.metadata },
@@ -1 +1 @@
1
- {"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../src/src/next/jobs/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAG7B,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAE/E,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,cAAc,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,2BAA2B,CAAC,cAAc;IACzD,aAAa,EAAE,cAAc,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,6BAA6B,CAC5C,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,CACxB,SAAQ,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,kBAAkB,CAAC;IACrE,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,CACV,KAAK,EAAE,6BAA6B,KACjC,OAAO,CAAC,QAAQ,GAAG,cAAc,CAAC,GAAG,QAAQ,GAAG,cAAc,CAAC;IACpE,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClE,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,2BAA2B,CAAC,cAAc,CAAC,KAC/C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,4BAA4B,CAC3C,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,CACxB,SACA,IAAI,CACF,6BAA6B,CAAC,IAAI,EAAE,cAAc,CAAC,EACnD,SAAS,CACV;IACD,0DAA0D;IAC1D,GAAG,EAAE,IAAI,CAAC;CACX;AAmBD,wBAAgB,sBAAsB,CACpC,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,EAExB,OAAO,EAAE,6BAA6B,CAAC,IAAI,EAAE,cAAc,CAAC,IAU1D,SAAS,cAAc,EACvB,SAAS,mBAAmB,kBAuF/B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,EAExB,OAAO,EAAE,4BAA4B,CAAC,IAAI,EAAE,cAAc,CAAC,IAQnD,SAAS,cAAc,kBAIhC"}
1
+ {"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../src/src/next/jobs/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAG7B,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAE/E,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,cAAc,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,2BAA2B,CAAC,cAAc;IACzD,aAAa,EAAE,cAAc,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,6BAA6B,CAC5C,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,CACxB,SAAQ,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,kBAAkB,CAAC;IACrE,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,CACV,KAAK,EAAE,6BAA6B,KACjC,OAAO,CAAC,QAAQ,GAAG,cAAc,CAAC,GAAG,QAAQ,GAAG,cAAc,CAAC;IACpE,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClE,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,2BAA2B,CAAC,cAAc,CAAC,KAC/C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,4BAA4B,CAC3C,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,CACxB,SACA,IAAI,CACF,6BAA6B,CAAC,IAAI,EAAE,cAAc,CAAC,EACnD,SAAS,CACV;IACD,0DAA0D;IAC1D,GAAG,EAAE,IAAI,CAAC;CACX;AAmBD,wBAAgB,sBAAsB,CACpC,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,EAExB,OAAO,EAAE,6BAA6B,CAAC,IAAI,EAAE,cAAc,CAAC,IAU1D,SAAS,cAAc,EACvB,SAAS,mBAAmB,kBAyF/B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,SAAS,aAAa,EAC1B,cAAc,GAAG,OAAO,EAExB,OAAO,EAAE,4BAA4B,CAAC,IAAI,EAAE,cAAc,CAAC,IAQnD,SAAS,cAAc,kBAIhC"}
@@ -81,7 +81,7 @@ function createJobsRouteHandler(options) {
81
81
  if (deferredTasks === "after" && options.after) {
82
82
  options.after(async () => {
83
83
  const result = await execution.result;
84
- await result.controller.runDeferredTasks();
84
+ await result.controller.runDeferredTasks(options.deferredTaskErrorHandler);
85
85
  });
86
86
  }
87
87
  return await finishResponse(response);
@@ -118,6 +118,16 @@ as database rows, job/run artifacts, checkpoints, logs, saved metadata, and the
118
118
  exact command or UI path used. Treat the provider or system's recorded response
119
119
  as more authoritative than a generic mapped error when deciding what failed.
120
120
 
121
+ ## Context-aware code review
122
+
123
+ - For code and design reviews, use `loom-torvalds-review` before the external
124
+ `linus-torvalds-skill` when both are active.
125
+ - Treat the Loom companion as the precedence and context layer. It maps the
126
+ upstream kernel-derived questions to web-app, shared-library/CLI, systems, or
127
+ explicit-prototype work and disables literal low-level rules elsewhere.
128
+ - In normal Loom Next.js consumers, default to the web-application profile
129
+ without asking. Use different profiles path by path for a mixed diff.
130
+
121
131
  ## Documentation and comments
122
132
 
123
133
  - Add JSDoc for new exported functions or methods when intent, key behavior, or
@@ -212,7 +222,10 @@ as more authoritative than a generic mapped error when deciding what failed.
212
222
 
213
223
  ## Commits
214
224
 
215
- - Use conventional commits with scopes for title.
225
+ - Use conventional commits with scopes for the title. Limit the subject line to
226
+ 50 characters, capitalize the first letter, do not end the subject line with a
227
+ period, use imperative mood (for example, `fix` instead of `fixed` or
228
+ `fixes`), and wrap the body at 72 characters.
216
229
  - In the body, include the motivation, summary of changes, and anything else of
217
230
  note.
218
231
  - At bottom: "Co-authored with <Assistant> (<model>, reasoning <level>)"
@@ -99,6 +99,33 @@ Use this skill when working on the shared jobs feature from a consuming app.
99
99
  - If the app has no always-on worker in the current environment, call out the
100
100
  manual runner or admin route needed to drain queued work.
101
101
 
102
+ ## Output sanitation and error disclosure
103
+
104
+ - Use `createJobOutputRedactor()` and pass the result as `outputSanitizer` on
105
+ the execution, response, or route-handler options. Do not implement redaction
106
+ only inside a text or HTML formatter; controller-level sanitation is what also
107
+ covers NDJSON, direct runners, HTTP output, and custom formatters.
108
+ - Redaction maps are ordered. Each exact-string or RegExp rule sees the prior
109
+ rule's result. Exact strings match every occurrence; RegExp rules replace
110
+ every match independent of `g`, `y`, or `lastIndex`. `true` means
111
+ `[REDACTED]`, and string replacements are literal rather than replacement
112
+ templates.
113
+ - Never add an empty exact-string rule. Loom rejects it without including
114
+ configured match or replacement values in the error.
115
+ - The policy recursively sanitizes string values from every controller log level
116
+ and `job.json()` without mutating caller-owned values. Sanitation failure
117
+ emits only the fixed `Job output sanitation failed.` event.
118
+ - Keep expected output, unexpected handler errors, and deferred-task errors as
119
+ distinct decisions. `handlerErrorMessage` opts into a generic literal while
120
+ omission preserves the legacy full stack. Use `deferredTaskErrorHandler`
121
+ separately and use `runDeferredTasksWithResult()` when a failure count affects
122
+ job or audit status; `runDeferredTasks()` keeps its legacy void result.
123
+ - Use `cancellationMessage: false` only when an app intentionally needs silent
124
+ cancellation while retaining the controller's cancellation flag.
125
+ - The boundary covers Loom job-event output, not `console.*`, provider logs,
126
+ audit metadata, URLs, thrown values retained in `execution.result`, external
127
+ log sinks, or object property names.
128
+
102
129
  ## Job Parameters and Validation
103
130
 
104
131
  Loom supports declarative job parameter definitions on each job's `meta` object.
@@ -26,9 +26,18 @@ contract.
26
26
  2. Run `loom add mail`.
27
27
  3. Review the materialized schema and generate the app-local migration.
28
28
  4. Replace the generated deny-all access function with the app's admin check.
29
- 5. Configure `POSTAL_API_KEY`, `POSTAL_HOST`, `POSTAL_FROM_EMAIL`, and
30
- `POSTAL_WEBHOOK_PUBLIC_KEYS`. The last value is a JSON array of RSA public
31
- JWKs with `kid`; it is not a shared secret.
29
+ 5. Configure `POSTAL_API_KEY`, `POSTAL_HOST`, `POSTAL_FROM_EMAIL`, optional
30
+ `POSTAL_FROM_NAME`, and `POSTAL_WEBHOOK_PUBLIC_KEYS`. Keep the sender values
31
+ structured:
32
+
33
+ ```dotenv
34
+ POSTAL_FROM_EMAIL=noreply@example.com
35
+ POSTAL_FROM_NAME=Example App
36
+ ```
37
+
38
+ `POSTAL_FROM_EMAIL` must be a bare address, never `Name <address>`.
39
+ `POSTAL_FROM_NAME` is optional. The webhook value is a JSON array of RSA
40
+ public JWKs with `kid`; it is not a shared secret.
32
41
  6. If jobs is active, register the generated `mail-drain` module in the app's
33
42
  full and metadata catalogs and choose an app-owned schedule.
34
43
  7. Configure Postal to POST signed events to the generated webhook route.
@@ -47,6 +56,8 @@ contract.
47
56
  supports an idempotency key.
48
57
  - Bound attachment size at the app/action boundary and never log attachment
49
58
  bodies, API keys, or webhook key material.
59
+ - Keep purpose-specific sender selection in the consumer. Use per-message
60
+ `fromEmail` and `fromName` overrides instead of adding domain policy to Loom.
50
61
 
51
62
  ## Testing
52
63