xone-agent-failure-packet 0.4.1__tar.gz

xone_agent_failure_packet-0.4.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.4.1
+
+Distribution release.
+
+- Add package publishing workflow and distribution documentation.
+- Prepare a release tag that includes the PyPI/TestPyPI publishing workflow.
+
+## 0.4.0
+
+GitHub Action release.
+
+- Add a read-only composite GitHub Action for building failure packets in CI.
+- Add `scripts/run-action.py` to write packets, step summaries, and downstream outputs.
+- Expose `packet-path` and `summary-json` Action outputs.
+- Keep Action behavior local and non-commenting by default.
+
+## 0.3.0
+
+Configuration and compatibility release.
+
+- Add `agent-failure-packet init` for local project configuration.
+- Add config auto-discovery from `.agent-failure-packet.yml`.
+- Add `agent-failure-packet validate` for run export schema checks.
+- Add Markdown snapshot coverage to detect accidental packet structure drift.
+
+## 0.2.0
+
+runtime fixture corpus and output profile release.
+
+- Add Codex CLI and GitHub Copilot agent-style failure fixtures.
+- Add Markdown output profiles: `incident` for full review and `issue` for compact sharing.
+- Redact secret-like query parameters while preserving documented placeholder credentials.
+- Expand fixture coverage for real-world agent failure shapes.
+
+## 0.1.0
+
+Initial local packet builder release.
+
+- Add `agent-failure-packet build` for Markdown and JSON packet output.
+- Add generic `agent-failure-packet.run.v1` input support.
+- Add `agent-failure-packet.packet.v1` output packets.
+- Add default and user-extended redaction before rendering.
+- Add fixture-backed tests for schema validation, rendering, CLI behavior, and redaction.

xone_agent_failure_packet-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 X-One-AI
+
+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.

xone_agent_failure_packet-0.4.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include CHANGELOG.md
+include README.zh-CN.md
+include action.yml
+include scripts/run-action.py
+recursive-include docs *.md
+recursive-include ops *.md
+recursive-include tests/fixtures *.json
+recursive-include tests/fixtures *.md

xone_agent_failure_packet-0.4.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: xone-agent-failure-packet
+Version: 0.4.1
+Summary: Create redacted, shareable debug packets from failed AI agent runs.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# agent-failure-packet
+
+Languages: English | [中文](./README.zh-CN.md)
+
+Create redacted, shareable debug packets from failed AI agent runs.
+
+## Status
+
+`P1` - v0.4.1 local packet builder and read-only GitHub Action.
+
+## Purpose
+
+Turn messy failed agent runs into safe evidence for issues, PRs, and incident review.
+
+## First Production Surface
+
+Local packet builder that accepts runtime exports and emits a redacted bundle.
+
+The first executable surface is specified in [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md).
+
+## Install
+
+From PyPI after publication:
+
+```bash
+python3 -m pip install xone-agent-failure-packet
+agent-failure-packet --version
+```
+
+From Homebrew after tap update:
+
+```bash
+brew install x-one-ai/tap/agent-failure-packet
+agent-failure-packet --version
+```
+
+From this repository:
+
+```bash
+python3 -m pip install -e .
+agent-failure-packet --version
+```
+
+## Usage
+
+Build a Markdown packet from a generic run export:
+
+```bash
+agent-failure-packet init --profile issue
+agent-failure-packet validate --input failed-run.json
+agent-failure-packet build --input tests/fixtures/runs/generic-failure-v1.json
+agent-failure-packet build --input failed-run.json --format markdown --output failure-packet.md
+agent-failure-packet build --input failed-run.json --format json --output failure-packet.json
+agent-failure-packet build --input failed-run.json --profile issue --output issue-packet.md
+agent-failure-packet build --input failed-run.json --redaction-policy .agent-failure-packet.yml
+```
+
+Input files use `schema_version: agent-failure-packet.run.v1`. JSON outputs use `schema_version: agent-failure-packet.packet.v1`.
+
+`agent-failure-packet build` auto-discovers `.agent-failure-packet.yml` from the current directory or its parents:
+
+```yaml
+schema_version: 1
+profile: issue
+# redaction_policy: .agent-failure-packet-redaction.yml
+```
+
+Markdown profiles:
+
+- `incident`: full packet with timeline, tool calls, errors, environment, redaction summary, checklist, and limitations.
+- `issue`: compact packet for GitHub issues or support tickets; omits deeper tool-call and environment sections.
+
+Fixture corpus:
+
+- `generic-failure-v1.json`
+- `codex-cli-failure-v1.json`
+- `github-copilot-agent-failure-v1.json`
+
+Example custom redaction policy:
+
+```yaml
+literals:
+  - internal-customer-id
+regexes:
+  - INTERNAL-[0-9]+
+```
+
+The default redaction policy cannot be disabled. The tool is local-first: it does not upload packet data, call a hosted service, or post comments.
+
+## GitHub Action
+
+Use the Action after checkout and point it at a failure export produced by your agent workflow:
+
+```yaml
+name: Agent Failure Packet
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  packet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: X-One-AI/agent-failure-packet@v0.4.1
+        with:
+          input: failed-run.json
+          profile: issue
+          output: agent-failure-packet.md
+```
+
+The Action writes a packet file, appends a compact packet to `GITHUB_STEP_SUMMARY`, and exposes `packet-path` and `summary-json` outputs. It is read-only and does not post PR comments.
+
+## Required Evidence
+
+- timeline
+- tool calls
+- errors
+- redaction summary
+- environment summary
+
+## Non-Goals
+
+- not a full tracing platform
+- not a hosted observability backend
+- not raw prompt/log sharing
+- not complete security coverage for every organization-specific secret
+
+## OPT Operating Model
+
+This project references the shared One Person Team workflow through [ops/opt-overlay.md](./ops/opt-overlay.md). Project-specific constraints live under [ops/constraints](./ops/constraints), and evolvable local skills live under [ops/skills](./ops/skills).
+
+## Blocked Inputs
+
+Inputs that require user or real-world data are recorded in `../x-one-skipped-inputs.md` and should not block foundation work.
+
+## Docs
+
+- [Product Foundation](./docs/product-foundation.md)
+- [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md)
+- [Changelog](./CHANGELOG.md)
+- [Publishing](./docs/publishing.md)
+- [Homebrew Packaging](./docs/homebrew.md)
+- [OPT Overlay](./ops/opt-overlay.md)
+- [Production Constraints](./ops/constraints/production.md)
+- [Main Entry Constraints](./ops/constraints/main-entry.md)
+- [Skill Evolution](./ops/skills/evolution.md)

xone_agent_failure_packet-0.4.1/README.md

@@ -0,0 +1,150 @@
+# agent-failure-packet
+
+Languages: English | [中文](./README.zh-CN.md)
+
+Create redacted, shareable debug packets from failed AI agent runs.
+
+## Status
+
+`P1` - v0.4.1 local packet builder and read-only GitHub Action.
+
+## Purpose
+
+Turn messy failed agent runs into safe evidence for issues, PRs, and incident review.
+
+## First Production Surface
+
+Local packet builder that accepts runtime exports and emits a redacted bundle.
+
+The first executable surface is specified in [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md).
+
+## Install
+
+From PyPI after publication:
+
+```bash
+python3 -m pip install xone-agent-failure-packet
+agent-failure-packet --version
+```
+
+From Homebrew after tap update:
+
+```bash
+brew install x-one-ai/tap/agent-failure-packet
+agent-failure-packet --version
+```
+
+From this repository:
+
+```bash
+python3 -m pip install -e .
+agent-failure-packet --version
+```
+
+## Usage
+
+Build a Markdown packet from a generic run export:
+
+```bash
+agent-failure-packet init --profile issue
+agent-failure-packet validate --input failed-run.json
+agent-failure-packet build --input tests/fixtures/runs/generic-failure-v1.json
+agent-failure-packet build --input failed-run.json --format markdown --output failure-packet.md
+agent-failure-packet build --input failed-run.json --format json --output failure-packet.json
+agent-failure-packet build --input failed-run.json --profile issue --output issue-packet.md
+agent-failure-packet build --input failed-run.json --redaction-policy .agent-failure-packet.yml
+```
+
+Input files use `schema_version: agent-failure-packet.run.v1`. JSON outputs use `schema_version: agent-failure-packet.packet.v1`.
+
+`agent-failure-packet build` auto-discovers `.agent-failure-packet.yml` from the current directory or its parents:
+
+```yaml
+schema_version: 1
+profile: issue
+# redaction_policy: .agent-failure-packet-redaction.yml
+```
+
+Markdown profiles:
+
+- `incident`: full packet with timeline, tool calls, errors, environment, redaction summary, checklist, and limitations.
+- `issue`: compact packet for GitHub issues or support tickets; omits deeper tool-call and environment sections.
+
+Fixture corpus:
+
+- `generic-failure-v1.json`
+- `codex-cli-failure-v1.json`
+- `github-copilot-agent-failure-v1.json`
+
+Example custom redaction policy:
+
+```yaml
+literals:
+  - internal-customer-id
+regexes:
+  - INTERNAL-[0-9]+
+```
+
+The default redaction policy cannot be disabled. The tool is local-first: it does not upload packet data, call a hosted service, or post comments.
+
+## GitHub Action
+
+Use the Action after checkout and point it at a failure export produced by your agent workflow:
+
+```yaml
+name: Agent Failure Packet
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  packet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: X-One-AI/agent-failure-packet@v0.4.1
+        with:
+          input: failed-run.json
+          profile: issue
+          output: agent-failure-packet.md
+```
+
+The Action writes a packet file, appends a compact packet to `GITHUB_STEP_SUMMARY`, and exposes `packet-path` and `summary-json` outputs. It is read-only and does not post PR comments.
+
+## Required Evidence
+
+- timeline
+- tool calls
+- errors
+- redaction summary
+- environment summary
+
+## Non-Goals
+
+- not a full tracing platform
+- not a hosted observability backend
+- not raw prompt/log sharing
+- not complete security coverage for every organization-specific secret
+
+## OPT Operating Model
+
+This project references the shared One Person Team workflow through [ops/opt-overlay.md](./ops/opt-overlay.md). Project-specific constraints live under [ops/constraints](./ops/constraints), and evolvable local skills live under [ops/skills](./ops/skills).
+
+## Blocked Inputs
+
+Inputs that require user or real-world data are recorded in `../x-one-skipped-inputs.md` and should not block foundation work.
+
+## Docs
+
+- [Product Foundation](./docs/product-foundation.md)
+- [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md)
+- [Changelog](./CHANGELOG.md)
+- [Publishing](./docs/publishing.md)
+- [Homebrew Packaging](./docs/homebrew.md)
+- [OPT Overlay](./ops/opt-overlay.md)
+- [Production Constraints](./ops/constraints/production.md)
+- [Main Entry Constraints](./ops/constraints/main-entry.md)
+- [Skill Evolution](./ops/skills/evolution.md)

xone_agent_failure_packet-0.4.1/README.zh-CN.md

@@ -0,0 +1,150 @@
+# agent-failure-packet
+
+语言： [English](./README.md) | 中文
+
+把失败的 AI agent 执行过程生成可脱敏、可分享的调试包。
+
+## 状态
+
+`P1` - v0.4.1 本地 packet builder 和 read-only GitHub Action。
+
+## 目的
+
+把混乱的失败 agent run 转成适合 issue、PR 和 incident review 使用的安全证据。
+
+## 第一生产化表面
+
+本地 packet builder：接受 agent runtime export，并输出脱敏后的可分享 bundle。
+
+第一可执行表面已在 [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md) 中定义。
+
+## 安装
+
+PyPI 发布后安装：
+
+```bash
+python3 -m pip install xone-agent-failure-packet
+agent-failure-packet --version
+```
+
+Homebrew tap 更新后安装：
+
+```bash
+brew install x-one-ai/tap/agent-failure-packet
+agent-failure-packet --version
+```
+
+在本仓库中运行：
+
+```bash
+python3 -m pip install -e .
+agent-failure-packet --version
+```
+
+## 使用
+
+从 generic run export 生成 Markdown packet：
+
+```bash
+agent-failure-packet init --profile issue
+agent-failure-packet validate --input failed-run.json
+agent-failure-packet build --input tests/fixtures/runs/generic-failure-v1.json
+agent-failure-packet build --input failed-run.json --format markdown --output failure-packet.md
+agent-failure-packet build --input failed-run.json --format json --output failure-packet.json
+agent-failure-packet build --input failed-run.json --profile issue --output issue-packet.md
+agent-failure-packet build --input failed-run.json --redaction-policy .agent-failure-packet.yml
+```
+
+输入文件使用 `schema_version: agent-failure-packet.run.v1`。JSON 输出使用 `schema_version: agent-failure-packet.packet.v1`。
+
+`agent-failure-packet build` 会从当前目录或上级目录自动发现 `.agent-failure-packet.yml`：
+
+```yaml
+schema_version: 1
+profile: issue
+# redaction_policy: .agent-failure-packet-redaction.yml
+```
+
+Markdown profiles：
+
+- `incident`：完整 packet，包含时间线、工具调用、错误、环境、脱敏摘要、checklist 和限制说明。
+- `issue`：适合 GitHub issue 或 support ticket 的紧凑 packet；省略更深的工具调用和环境章节。
+
+Fixture corpus：
+
+- `generic-failure-v1.json`
+- `codex-cli-failure-v1.json`
+- `github-copilot-agent-failure-v1.json`
+
+自定义脱敏策略示例：
+
+```yaml
+literals:
+  - internal-customer-id
+regexes:
+  - INTERNAL-[0-9]+
+```
+
+默认脱敏策略不能关闭。本工具是 local-first：不会上传 packet 数据，不调用 hosted service，也不会自动发布 comment。
+
+## GitHub Action
+
+在 checkout 之后使用 Action，并指向 agent workflow 生成的 failure export：
+
+```yaml
+name: Agent Failure Packet
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  packet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: X-One-AI/agent-failure-packet@v0.4.1
+        with:
+          input: failed-run.json
+          profile: issue
+          output: agent-failure-packet.md
+```
+
+Action 会写出 packet 文件，把紧凑 packet 追加到 `GITHUB_STEP_SUMMARY`，并暴露 `packet-path` 和 `summary-json` outputs。它是 read-only，不会发布 PR comment。
+
+## 必要证据
+
+- 时间线
+- 工具调用
+- 错误
+- 脱敏摘要
+- 环境摘要
+
+## 非目标
+
+- 不做完整 tracing 平台
+- 不做 hosted observability backend
+- 不分享原始 prompt 或 log
+- 不承诺覆盖所有组织特有 secret 的完整安全能力
+
+## OPT 运行模型
+
+本项目通过 [ops/opt-overlay.md](./ops/opt-overlay.md) 引用共享 One Person Team 工作流。项目自己的约束放在 [ops/constraints](./ops/constraints)，可演进 skill 放在 [ops/skills](./ops/skills)。
+
+## 暂缺输入
+
+需要用户或真实世界数据补充的内容记录在 `../x-one-skipped-inputs.md`，不阻塞基础建设。
+
+## 文档
+
+- [产品基础](./docs/product-foundation.md)
+- [Packet Builder Design](./docs/superpowers/specs/2026-06-13-packet-builder-design.md)
+- [Changelog](./CHANGELOG.md)
+- [Publishing](./docs/publishing.md)
+- [Homebrew Packaging](./docs/homebrew.md)
+- [OPT Overlay](./ops/opt-overlay.md)
+- [生产约束](./ops/constraints/production.md)
+- [主入口约束](./ops/constraints/main-entry.md)
+- [Skill 演进](./ops/skills/evolution.md)

xone_agent_failure_packet-0.4.1/action.yml

@@ -0,0 +1,49 @@
+name: Agent Failure Packet
+description: Build a redacted, shareable packet from a failed AI agent run export.
+
+inputs:
+  input:
+    description: Path to an agent-failure-packet.run.v1 JSON export.
+    required: true
+  format:
+    description: Output format.
+    required: false
+    default: markdown
+  profile:
+    description: Markdown output profile.
+    required: false
+    default: incident
+  output:
+    description: Output packet path.
+    required: false
+    default: agent-failure-packet.md
+  redaction-policy:
+    description: Optional YAML redaction policy path.
+    required: false
+    default: ""
+
+outputs:
+  packet-path:
+    description: Path to the generated packet.
+    value: ${{ steps.packet.outputs.packet-path }}
+  summary-json:
+    description: Compact JSON summary for downstream steps.
+    value: ${{ steps.packet.outputs.summary-json }}
+
+runs:
+  using: composite
+  steps:
+    - name: Build agent failure packet
+      id: packet
+      shell: bash
+      run: |
+        policy_args=()
+        if [ -n "${{ inputs.redaction-policy }}" ]; then
+          policy_args=(--redaction-policy "${{ inputs.redaction-policy }}")
+        fi
+        python3 scripts/run-action.py \
+          --input "${{ inputs.input }}" \
+          --format "${{ inputs.format }}" \
+          --profile "${{ inputs.profile }}" \
+          --output "${{ inputs.output }}" \
+          "${policy_args[@]}"

xone_agent_failure_packet-0.4.1/docs/homebrew.md

@@ -0,0 +1,37 @@
+# Homebrew Packaging
+
+`agent-failure-packet` is distributed through the X-One tap.
+
+## User Install
+
+```bash
+brew tap x-one-ai/tap
+brew trust --formula x-one-ai/tap/agent-failure-packet
+brew install x-one-ai/tap/agent-failure-packet
+agent-failure-packet --version
+```
+
+## Tap Repository
+
+```text
+X-One-AI/homebrew-tap
+```
+
+Formula path:
+
+```text
+Formula/agent-failure-packet.rb
+```
+
+## Formula Requirements
+
+- Install the Python CLI as `agent-failure-packet`.
+- Use the released `xone-agent-failure-packet` source distribution.
+- Vendor Python dependencies as Homebrew resources.
+- Run `agent-failure-packet --version` in the formula test.
+
+## Current Target
+
+```text
+xone-agent-failure-packet==0.4.1
+```