Add TypeScript task SDK public interface

[shivaam]

Adds a minimal @apache-airflow/ts-sdk package that defines the public TypeScript task-handler contract.

Summary:

• Add explicit Dag-scoped task registration with separate dagId and taskId fields.
• Add task context, task handler, and TaskClient interfaces.
• Keep the first public surface aligned with the Go and Java SDKs: Variables, Connections, and XCom only.
• Expose idiomatic TypeScript names such as dagId, taskId, runId, mapIndex, and connId; coordinator/runtime code will map those names to Airflow schema fields.
• Add standalone package config, lint/format/test/build scripts, README, and focused Vitest coverage, including type-level assertions for the public API shape.

This PR has intentionally been narrowed to the user-facing SDK interface only. It does not include coordinator-mode execution, edge-worker execution, generated supervisor schema types, or Python coordinator registration. Those are intended as follow-up PRs built on this public interface.

Example intent:

fromairflow.sdkimportdag, task@dagdefsales_pipeline():
@task.stub(queue="typescript")defextract(): ...
@task.stub(queue="typescript")deftransform(extracted): ...
transform(extract())
sales_pipeline()

import{registerTask}from"@apache-airflow/ts-sdk";registerTask({dagId: "sales_pipeline",taskId: "extract"},async({ client })=>{constconnection=awaitclient.getConnection("sales_db");constrowCount=Number((awaitclient.getVariable("daily_row_count"))??"0");return{connectionId: connection?.connId??null,
rowCount,};});registerTask({dagId: "sales_pipeline",taskId: "transform"},async({ client })=>{constextracted=awaitclient.getXCom<{rowCount: number}>({key: "return_value",taskId: "extract",});return{transformedRows: extracted?.rowCount??0,};});

The Python stub defines the Dag dependency graph. The TypeScript handler does the work and uses TaskClient for task-time Airflow data access. The follow-up coordinator runtime will launch Node.js, find the registered handler for that Dag/task pair, and run it.

Next steps:

• Add coordinator-mode execution in a follow-up PR: TypeScript runtime, coordinator TaskClient implementation, supervisor protocol/schema wiring, logging, cancellation handling, and Python TypescriptCoordinator registration.
• Add coordinator schema-mapping tests that validate camelCase public options serialize to the supervisor schema's snake_case fields.
• Add Airflow-level integration coverage for coordinator-mode TypeScript tasks, including the daemon-based end-to-end path we used locally.
• Keep edge-worker execution separate from coordinator mode so the public SDK, coordinator runtime, and future edge runtime can evolve independently.
• Revisit higher-level TypeScript Dag authoring and bundle ergonomics after coordinator-mode execution is reviewed, instead of expanding this first interface PR.

Testing:

• pnpm -C ts-sdk format:check
• pnpm -C ts-sdk lint
• pnpm -C ts-sdk typecheck
• pnpm -C ts-sdk test
• pnpm -C ts-sdk run build
• pnpm -C ts-sdk pack --dry-run
• ~/.local/bin/prek run --from-ref upstream/main --stage pre-commit
• ~/.local/bin/prek run --from-ref upstream/main --stage manual

Was generative AI tooling used to co-author this PR?

• Yes - Codex (GPT-5)

Generated-by: Codex (GPT-5) following the guidelines

---

Drafted-by: Codex (GPT-5) (no human review before posting)

[shivaam]

@jason810496@uranusjr Appreciate your feedback

[shivaam]

Addressed feedback from @ashb offline just on the user interface.

[pierrejeambrun]

Really nice first slice.

Also +1 on the ts-sdk naming — it's consistent with the Java SDK naming itself after the author's language (it's actually Kotlin under the hood), so no change needed if anyone questions it.

A few small consistency notes inline

[uranusjr]

I think in general this is good. We should add a pre-commit hook to lint ts files in here.

[shivaam]

I think in general this is good. We should add a pre-commit hook to lint ts files in here.

@uranusjr I have added a root prek hook for the TS SDK, following the existing Airflow TS/UI hooks. It runs the SDK’s local lint/format/typecheck scripts and auto-fixes lint/format issues where possible.

[jason810496]

Thanks a lot for being patient and continue one TS-SDK, and sorry for pushing back on the user interface.

[shivaam]

Addressed all 3 comments form @jason810496

[jason810496]

Thanks for the update. LGTM.

[shivaam]

@uranusjr Thanks for the reviews. Would it be possible to merge this PR so I can build upon it and add the protocol PR.