codex-task 0.2.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "codex-task",
+  "version": "0.2.0",
+  "description": "Delegate focused text, image, and workspace tasks to CodexTask",
+  "author": {
+    "name": "wang121ye",
+    "url": "https://github.com/wangyendt"
+  },
+  "homepage": "https://github.com/wangyendt/codex-task",
+  "repository": "https://github.com/wangyendt/codex-task",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "codex",
+    "images",
+    "tasks"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "CodexTask",
+    "shortDescription": "Delegate text, image, and workspace tasks",
+    "longDescription": "A companion skill for routing focused text, image, and workspace tasks through the CodexTask CLI.",
+    "developerName": "wang121ye",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/wangyendt/codex-task",
+    "defaultPrompt": [
+      "Delegate this focused task with CodexTask.",
+      "Generate this image through CodexTask.",
+      "Send this workspace task to a Codex worker."
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ye.wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# CodexTask
+
+> Give another AI agent a focused errand—and get back text, images, or finished work. Powered by your existing Codex setup.
+
+[中文文档](./README.zh-CN.md) · [PRD](./docs/PRD.md) · [Companion skill](./skills/codex-task/SKILL.md)
+
+CodexTask turns Codex into a small, composable worker for other agents. It ships one CLI, one TypeScript API, and one installable skill for three jobs:
+
+- focused text-to-text tasks;
+- text-to-image and image-to-image generation;
+- bounded workspace tasks through the official Codex SDK.
+
+No daemon. No hosted service. No extra API key. Results are stable JSON that another agent can consume.
+
+> [!IMPORTANT]
+> CodexTask is an independent, unofficial open-source project. It is not affiliated with, endorsed by, or sponsored by OpenAI. Codex and OpenAI are trademarks of OpenAI.
+
+## Quick start
+
+Requirements: Node.js 20+ and an existing Codex login (`codex login`).
+
+```bash
+npm install -g codex-task
+codex-task doctor
+```
+
+Delegate a text result:
+
+```bash
+codex-task text "Turn these notes into a crisp release announcement" \
+  --backend direct
+```
+
+Generate an image that will not be removed by temporary-file cleanup:
+
+```bash
+codex-task image "A precise exploded-view diagram of a compact robot joint" \
+  --backend direct \
+  --size 1536x1024 \
+  --quality high \
+  --output ./artifacts
+```
+
+Edit an image:
+
+```bash
+codex-task image "Keep the object; replace the background with a clean workshop" \
+  --backend direct \
+  --image ./reference.png \
+  --output ./artifacts
+```
+
+Delegate repository work:
+
+```bash
+codex-task task "Implement the requested feature and run focused tests" \
+  --backend sdk \
+  --cwd /absolute/path/to/repo
+```
+
+Every command writes a machine-readable result:
+
+```json
+{
+  "status": "completed",
+  "taskId": "e6fe7ed7-72de-4b27-8b6e-08152192d6cb",
+  "backend": "direct",
+  "text": "...",
+  "effectiveModel": "gpt-5.6-sol",
+  "reasoningEffort": "medium",
+  "artifacts": []
+}
+```
+
+## Pick the backend
+
+CodexTask never guesses. Direct is the CLI default, but workspace tasks require an explicit SDK backend.
+
+| Capability | `direct` | `sdk` |
+| --- | --- | --- |
+| Focused text result | Yes | Yes |
+| Text-to-image / image-to-image | Yes, native result extraction | Yes, via the installed `$imagegen` skill |
+| Shell and file edits | No | Yes |
+| Project rules and local tools | No | Yes |
+| Local Codex skills | No | Normal Codex discovery |
+| Transport | Unofficial ChatGPT Codex Responses | Official `@openai/codex-sdk` |
+| Stability | Experimental | Supported SDK surface |
+
+Direct reuses `$CODEX_HOME/auth.json`, Codex installation metadata, TLS impersonation, and the private ChatGPT Codex Responses endpoint. Inputs are still sent to ChatGPT. The interface may change without notice.
+
+The SDK backend defaults to:
+
+```text
+sandbox: danger-full-access
+approval: never
+network: true
+```
+
+That combination is intentionally powerful: it can read and write outside the workspace, execute commands, and use the network without asking for approval. Only delegate trusted prompts and repositories.
+
+## Agent follow-ups
+
+SDK tasks are single-turn first. If the worker needs clarification, the result is not an error:
+
+```json
+{
+  "status": "needs_input",
+  "taskId": "...",
+  "threadId": "...",
+  "questions": ["Should the API preserve the legacy response shape?"],
+  "artifacts": []
+}
+```
+
+Ask the user, then resume the same Codex thread:
+
+```bash
+printf '%s' "Yes, preserve it." | codex-task resume <task-id>
+```
+
+Pass `--no-followup` to require reasonable assumptions and a completed/failed result in one caller turn. It does not guarantee the model succeeds.
+
+## Use from another agent
+
+This repository ships `skills/codex-task/SKILL.md`. It teaches a calling agent when to choose text, image, task, or resume. It is a companion skill, not a skill injected into the Codex worker.
+
+Install it with [skillmanager](https://github.com/wangyendt/skillmanager):
+
+```bash
+npm install -g @wang121ye/skillmanager
+skillmanager install https://github.com/wangyendt/codex-task --global
+```
+
+Or locate the copy included in the npm package:
+
+```bash
+codex-task skill path
+```
+
+The repository also includes `.codex-plugin/plugin.json` for plugin-compatible distribution.
+
+## TypeScript API
+
+```ts
+import { generateImage, generateText, runTask } from "codex-task";
+
+const copy = await generateText({
+  prompt: "Write a launch headline and three supporting bullets.",
+  backend: "direct",
+});
+
+const image = await generateImage({
+  prompt: "A restrained isometric illustration of agent-to-agent delegation.",
+  backend: "direct",
+  output: "./artifacts",
+  quality: "high",
+});
+
+const work = await runTask({
+  prompt: "Add the feature and run focused tests.",
+  backend: "sdk",
+  workingDirectory: "/absolute/path/to/repo",
+});
+```
+
+For progress events:
+
+```ts
+import { streamTaskEvents } from "codex-task";
+
+for await (const event of streamTaskEvents({
+  kind: "text",
+  options: { prompt: "Summarize this decision", backend: "direct" },
+})) {
+  console.log(event);
+}
+```
+
+The event stream reports item and task progress; it is not guaranteed token streaming.
+
+## Image controls
+
+```text
+references   0–5 local PNG/JPEG/WebP/GIF files
+size         auto or WIDTHxHEIGHT; longest edge ≤ 3840
+quality      auto | low | medium | high
+background   auto | opaque | transparent
+count        1–10
+concurrency  1–3, default 1
+```
+
+Each reference may be at most 20 MiB, with a 50 MiB combined limit. Existing outputs are rejected unless `--overwrite` is supplied. Completed images are atomically saved immediately, so a later batch failure does not discard earlier artifacts.
+
+## Inputs and output
+
+Long prompts can come from a file or stdin:
+
+```bash
+codex-task text --prompt-file task.md --backend direct
+printf '%s' "$PROMPT" | codex-task task --backend sdk --cwd .
+```
+
+The positional prompt, `--prompt-file`, and stdin are mutually exclusive.
+
+Default stdout is one JSON result. `--stream` switches stdout to JSONL events. Diagnostics go to stderr. Exit codes are:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | `completed` or `needs_input` |
+| `1` | execution failure |
+| `2` | invalid arguments or configuration |
+| `130` | cancellation or timeout |
+
+## Models and configuration
+
+The SDK backend leaves model and reasoning unset unless you override them, allowing normal Codex configuration discovery.
+
+Direct resolves its model in this order:
+
+1. `--model` / API option;
+2. Codex `config.toml`;
+3. the preferred visible model in `models_cache.json`;
+4. compatibility fallback.
+
+It supports classic Responses and Responses Lite encoders. With a current Codex model catalog, text defaults to `gpt-5.6-sol` with `medium` reasoning. The private Responses Lite route rejects hosted `image_generation`, so Direct image requests are preflighted to the compatible classic `gpt-5.5` model before any request is sent. The final JSON always reports `effectiveModel` and `reasoningEffort`.
+
+Configuration precedence is API/CLI → `CODEX_TASK_*` environment variables → user config → Codex config → fallback. The user config is `config.json` under the standard platform config directory; run `codex-task doctor` to see the exact path.
+
+For migration, `CODEXERRAND_*` variables and the former CodexErrand config/task paths are recognized only when their `CODEX_TASK_*` or CodexTask equivalents are absent. New state is always written under CodexTask paths.
+
+Useful variables include:
+
+```text
+CODEX_TASK_MODEL
+CODEX_TASK_REASONING
+CODEX_TASK_PROXY
+CODEX_TASK_CODEX_HOME
+CODEX_TASK_TEXT_TIMEOUT_MS
+CODEX_TASK_IMAGE_TIMEOUT_MS
+CODEX_TASK_SDK_TIMEOUT_MS
+CODEX_TASK_RETRIES
+```
+
+## Temporary data
+
+- Images without `--output` live under the platform temporary directory and expire after 24 hours.
+- Pending `needs_input` metadata lives under the platform state directory and expires after 7 days.
+- Managed temporary artifacts are capped at 1 GiB.
+- Explicit output paths are user data and are never removed by `codex-task gc`.
+- Official SDK sessions remain managed by Codex under `$CODEX_HOME`; CodexTask does not delete them.
+
+## Development and releases
+
+```bash
+npm install
+npm run verify
+```
+
+`npm run verify` runs lint, type checking, unit tests, build, package inspection, and a clean install/import smoke test. Live Direct endpoint tests are opt-in and never run in CI:
+
+```bash
+RUN_DIRECT_E2E=1 npm run test:e2e
+```
+
+Every push to `main` triggers an automatic patch bump. A second workflow verifies the package, publishes through npm Trusted Publishing, and creates a `vX.Y.Z` tag. Repository setup is documented in [Release setup](./docs/RELEASING.md).
+
+## Acknowledgements
+
+The Direct backend is derived in part from the MIT-licensed [`lawrencewzen/imgen`](https://github.com/lawrencewzen/imgen). See [third-party notices](./THIRD_PARTY_NOTICES.md).
+
+## License
+
+MIT © 2026 ye.wang

package/README.zh-CN.md

@@ -0,0 +1,209 @@
+# CodexTask
+
+> 把一个明确的小任务交给另一个 AI Agent，拿回文本、图片或已经完成的工作。直接复用你现有的 Codex 环境。
+
+[English](./README.md) · [产品需求文档](./docs/PRD.md) · [Companion skill](./skills/codex-task/SKILL.md)
+
+CodexTask 把 Codex 封装成可供其他 Agent 调用的轻量 worker，统一提供三类能力：
+
+- 文生文；
+- 文生图和图生图；
+- 通过官方 Codex SDK 执行边界明确的工作区任务。
+
+没有 daemon，没有托管服务，也不需要额外 API key。所有结果都使用适合 Agent 解析的稳定 JSON。
+
+> [!IMPORTANT]
+> CodexTask 是独立的非官方开源项目，与 OpenAI 不存在隶属、认可或赞助关系。Codex 与 OpenAI 为 OpenAI 的商标。
+
+## 30 秒上手
+
+需要 Node.js 20+，并已执行过 `codex login`。
+
+```bash
+npm install -g codex-task
+codex-task doctor
+```
+
+生成文本：
+
+```bash
+codex-task text "把这些笔记整理成简洁的发布公告" --backend direct
+```
+
+生成持久图片：
+
+```bash
+codex-task image "精确、克制的机器人关节爆炸图" \
+  --backend direct \
+  --size 1536x1024 \
+  --quality high \
+  --output ./artifacts
+```
+
+基于参考图编辑：
+
+```bash
+codex-task image "保留主体，把背景换成整洁的工作室" \
+  --backend direct \
+  --image ./reference.png \
+  --output ./artifacts
+```
+
+委派仓库任务：
+
+```bash
+codex-task task "实现这个功能并运行聚焦测试" \
+  --backend sdk \
+  --cwd /absolute/path/to/repo
+```
+
+## 两种后端
+
+CodexTask 不猜测后端。CLI 默认是 Direct，但工作区任务必须显式写出 SDK。
+
+| 能力 | `direct` | `sdk` |
+| --- | --- | --- |
+| 独立文本结果 | 支持 | 支持 |
+| 文生图 / 图生图 | 原生提取图片 | 通过已安装的 `$imagegen` skill |
+| shell 和文件修改 | 不支持 | 支持 |
+| 项目 rules 和本地工具 | 不支持 | 支持 |
+| 本地 Codex skills | 不支持 | 按 Codex 正常发现 |
+| 底层 | 非官方 ChatGPT Codex Responses | 官方 `@openai/codex-sdk` |
+
+Direct 会复用 `$CODEX_HOME/auth.json`、Codex installation metadata、TLS impersonation 和 ChatGPT 私有 Codex Responses 接口。输入仍会发往 ChatGPT，接口也可能随时变化。
+
+SDK task 默认权限为：
+
+```text
+sandbox: danger-full-access
+approval: never
+network: true
+```
+
+这意味着它可以访问工作区外路径、执行命令并联网，而且不会询问权限。只把可信 prompt 和可信仓库交给它。
+
+## 追问与恢复
+
+SDK 默认先执行一个 turn。确实需要澄清时返回：
+
+```json
+{
+  "status": "needs_input",
+  "taskId": "...",
+  "threadId": "...",
+  "questions": ["是否必须保持旧响应格式？"],
+  "artifacts": []
+}
+```
+
+向用户确认后恢复同一个 Codex thread：
+
+```bash
+printf '%s' "是，必须保持。" | codex-task resume <task-id>
+```
+
+`--no-followup` 会要求 Codex 使用合理假设，只能完成或失败；它不保证模型一定成功。
+
+## 安装给其他 Agent
+
+仓库内置 `skills/codex-task/SKILL.md`。它教调用方 Agent 选择 `text`、`image`、`task` 或 `resume`，并不是注入底层 Codex worker 的 skill。
+
+使用 [skillmanager](https://github.com/wangyendt/skillmanager) 安装：
+
+```bash
+npm install -g @wang121ye/skillmanager
+skillmanager install https://github.com/wangyendt/codex-task --global
+```
+
+也可以查看 npm 包内 skill 的位置：
+
+```bash
+codex-task skill path
+```
+
+## TypeScript API
+
+```ts
+import { generateImage, generateText, runTask } from "codex-task";
+
+const text = await generateText({
+  prompt: "写一个标题和三个卖点。",
+  backend: "direct",
+});
+
+const image = await generateImage({
+  prompt: "Agent 之间传递任务的克制等距插画。",
+  backend: "direct",
+  output: "./artifacts",
+});
+
+const work = await runTask({
+  prompt: "实现功能并运行聚焦测试。",
+  backend: "sdk",
+  workingDirectory: "/absolute/path/to/repo",
+});
+```
+
+## 图片参数
+
+```text
+参考图       0–5 张本地 PNG/JPEG/WebP/GIF
+size         auto 或 WIDTHxHEIGHT，最长边 ≤3840
+quality      auto | low | medium | high
+background   auto | opaque | transparent
+count        1–10
+concurrency  1–3，默认 1
+```
+
+单张参考图不超过 20 MiB，总和不超过 50 MiB。默认拒绝覆盖已有文件，只有显式传 `--overwrite` 才会替换。每张图片完成后立即原子落盘，后续图片失败不会丢失已经生成的产物。
+
+## Agent 友好的输出
+
+- 默认 stdout 是一个最终 JSON。
+- `--stream` 将 stdout 改为 JSONL 进度事件，不保证逐 token 输出。
+- 诊断信息写 stderr。
+- exit code：完成/追问为 `0`，运行失败为 `1`，参数错误为 `2`，取消或超时为 `130`。
+
+长 prompt 推荐使用文件或 stdin：
+
+```bash
+codex-task text --prompt-file task.md --backend direct
+printf '%s' "$PROMPT" | codex-task task --backend sdk --cwd .
+```
+
+## 模型和配置
+
+SDK 默认不覆写模型和 reasoning，继续按 Codex 正常配置读取。
+
+Direct 按以下顺序选择模型：显式参数 → Codex `config.toml` → `models_cache.json` 首选模型 → 兼容 fallback。它同时实现 classic Responses 和 Responses Lite encoder；当前模型目录下文本默认是 `gpt-5.6-sol + medium`。私有 Responses Lite 路由会拒绝托管 `image_generation`，因此 Direct 图片会在发出请求前选择兼容的 classic `gpt-5.5`。最终 JSON 会返回真实的 `effectiveModel` 和 `reasoningEffort`。
+
+配置优先级为 API/CLI → `CODEX_TASK_*` 环境变量 → 用户配置 → Codex 配置 → fallback。运行 `codex-task doctor` 可以查看真实路径和解析结果。迁移期间，仅当新的变量或路径不存在时才兼容读取旧的 `CODEXERRAND_*` 环境变量以及 CodexErrand 配置/待恢复任务；新状态始终写入 CodexTask 路径。
+
+## 临时文件
+
+- 不传 `--output` 的图片放系统临时目录，默认 24 小时过期。
+- `needs_input` 的小型状态放平台 state 目录，默认保存 7 天。
+- 临时产物总上限 1 GiB。
+- 显式 `--output` 下的文件属于用户数据，`codex-task gc` 永远不会删除。
+- 官方 SDK 的 session 仍由 Codex 自己保存在 `$CODEX_HOME`，CodexTask 不删除。
+
+## 开发和发布
+
+```bash
+npm install
+npm run verify
+```
+
+`verify` 会执行 lint、类型检查、单元测试、构建、npm 包内容检查和干净安装/import smoke test。真实 Direct endpoint 测试必须显式开启，CI 永远不会运行：
+
+```bash
+RUN_DIRECT_E2E=1 npm run test:e2e
+```
+
+每次 push 到 `main` 自动发布 patch 版本。详细设置见 [发布说明](./docs/RELEASING.md)。
+
+## 致谢与许可
+
+Direct 后端部分技术和 MIT 代码源自 [`lawrencewzen/imgen`](https://github.com/lawrencewzen/imgen)，详见 [第三方声明](./THIRD_PARTY_NOTICES.md)。
+
+MIT © 2026 ye.wang

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+## imgen
+
+CodexTask's Direct backend is derived in part from ideas and MIT-licensed code in [`lawrencewzen/imgen`](https://github.com/lawrencewzen/imgen), including Codex OAuth handling, installation identity, TLS impersonation, Codex-like request metadata, image input encoding, and image SSE extraction.
+
+The upstream license at the reviewed revision states:
+
+```text
+MIT License
+
+Copyright (c) 2026 aisparkedu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+CodexTask substantially restructures the implementation, adds text and SDK backends, structured task results, Responses Lite encoding, state management, validation, tests, and distribution assets.
+
+## OpenAI Codex SDK
+
+CodexTask depends on `@openai/codex-sdk` for its SDK backend. Codex and OpenAI are trademarks of OpenAI. Use of the dependency does not imply affiliation, endorsement, or sponsorship.

package/dist/api.d.ts

@@ -0,0 +1,8 @@
+import type { ImageOptions, ResumeTaskOptions, TaskEvent, TaskRequest, TaskResult, TextOptions, WorkspaceTaskOptions } from "./types.js";
+export declare function generateText(options: TextOptions): Promise<TaskResult>;
+export declare function generateImage(options: ImageOptions): Promise<TaskResult>;
+export declare function runTask(options: WorkspaceTaskOptions): Promise<TaskResult>;
+export declare function resumeTask(options: ResumeTaskOptions): Promise<TaskResult>;
+export declare function streamTaskEvents(request: TaskRequest): AsyncGenerator<TaskEvent>;
+export declare function dispatch(request: TaskRequest): Promise<TaskResult>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAMV,YAAY,EAEZ,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,WAAW,EACX,oBAAoB,EACrB,MAAM,YAAY,CAAC;AA0EpB,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA0C5E;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAwB9E;AAwDD,wBAAsB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BhF;AA4CD,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqChF;AAsBD,wBAAuB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC,CAavF;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAWlE"}