akernel-runtime 0.1.0__tar.gz

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 (89) hide show
  1. akernel_runtime-0.1.0/.env.example +4 -0
  2. akernel_runtime-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +34 -0
  3. akernel_runtime-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md +23 -0
  4. akernel_runtime-0.1.0/.github/pull_request_template.md +13 -0
  5. akernel_runtime-0.1.0/.github/workflows/ci.yml +76 -0
  6. akernel_runtime-0.1.0/.github/workflows/release.yml +158 -0
  7. akernel_runtime-0.1.0/CHANGELOG.md +65 -0
  8. akernel_runtime-0.1.0/CODE_OF_CONDUCT.md +24 -0
  9. akernel_runtime-0.1.0/CONTRIBUTING.md +56 -0
  10. akernel_runtime-0.1.0/LICENSE +201 -0
  11. akernel_runtime-0.1.0/MANIFEST.in +18 -0
  12. akernel_runtime-0.1.0/NOTICE +4 -0
  13. akernel_runtime-0.1.0/PKG-INFO +270 -0
  14. akernel_runtime-0.1.0/README.md +243 -0
  15. akernel_runtime-0.1.0/SECURITY.md +35 -0
  16. akernel_runtime-0.1.0/docs/00-vision.md +39 -0
  17. akernel_runtime-0.1.0/docs/01-architecture.md +281 -0
  18. akernel_runtime-0.1.0/docs/02-execution-plan.md +103 -0
  19. akernel_runtime-0.1.0/docs/03-cli-mvp.md +369 -0
  20. akernel_runtime-0.1.0/docs/04-evaluation.md +140 -0
  21. akernel_runtime-0.1.0/docs/05-local-wake.md +63 -0
  22. akernel_runtime-0.1.0/docs/06-skill-compiler.md +41 -0
  23. akernel_runtime-0.1.0/docs/07-release-and-ci.md +119 -0
  24. akernel_runtime-0.1.0/docs/08-open-source-plan.md +106 -0
  25. akernel_runtime-0.1.0/docs/09-product-roadmap.md +123 -0
  26. akernel_runtime-0.1.0/docs/10-benchmark-evidence.md +63 -0
  27. akernel_runtime-0.1.0/docs/11-publishing-setup.md +97 -0
  28. akernel_runtime-0.1.0/examples/benchmarks/phase2/01-routing.json +22 -0
  29. akernel_runtime-0.1.0/examples/benchmarks/phase2/02-memory.json +20 -0
  30. akernel_runtime-0.1.0/examples/benchmarks/phase2/03-budget-profiles.json +21 -0
  31. akernel_runtime-0.1.0/examples/benchmarks/scale/01-context-pressure.json +22 -0
  32. akernel_runtime-0.1.0/examples/benchmarks/scale/02-agent-editing.json +21 -0
  33. akernel_runtime-0.1.0/examples/benchmarks/scale/03-global-memory-marketplace.json +20 -0
  34. akernel_runtime-0.1.0/examples/evals/phase2.json +22 -0
  35. akernel_runtime-0.1.0/examples/marketplace/skills/index.json +66 -0
  36. akernel_runtime-0.1.0/examples/skills/context_budget.json +28 -0
  37. akernel_runtime-0.1.0/examples/skills/edit_file.json +28 -0
  38. akernel_runtime-0.1.0/examples/skills/markdown/context_budget.md +43 -0
  39. akernel_runtime-0.1.0/packages/npm/akernel/README.md +22 -0
  40. akernel_runtime-0.1.0/packages/npm/akernel/bin/akernel.js +63 -0
  41. akernel_runtime-0.1.0/packages/npm/akernel/package.json +36 -0
  42. akernel_runtime-0.1.0/pyproject.toml +44 -0
  43. akernel_runtime-0.1.0/scripts/install_remote.ps1 +23 -0
  44. akernel_runtime-0.1.0/scripts/release_check.ps1 +82 -0
  45. akernel_runtime-0.1.0/setup.cfg +4 -0
  46. akernel_runtime-0.1.0/setup.cmd +4 -0
  47. akernel_runtime-0.1.0/setup.ps1 +116 -0
  48. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/PKG-INFO +270 -0
  49. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/SOURCES.txt +87 -0
  50. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/dependency_links.txt +1 -0
  51. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/entry_points.txt +2 -0
  52. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/requires.txt +4 -0
  53. akernel_runtime-0.1.0/src/akernel_runtime.egg-info/top_level.txt +1 -0
  54. akernel_runtime-0.1.0/src/context_kernel/__init__.py +4 -0
  55. akernel_runtime-0.1.0/src/context_kernel/__main__.py +5 -0
  56. akernel_runtime-0.1.0/src/context_kernel/agent_reports.py +188 -0
  57. akernel_runtime-0.1.0/src/context_kernel/benchmarks.py +493 -0
  58. akernel_runtime-0.1.0/src/context_kernel/budget.py +72 -0
  59. akernel_runtime-0.1.0/src/context_kernel/cli.py +2953 -0
  60. akernel_runtime-0.1.0/src/context_kernel/context.py +161 -0
  61. akernel_runtime-0.1.0/src/context_kernel/evals.py +347 -0
  62. akernel_runtime-0.1.0/src/context_kernel/global_memory.py +126 -0
  63. akernel_runtime-0.1.0/src/context_kernel/loop.py +1617 -0
  64. akernel_runtime-0.1.0/src/context_kernel/marketplace.py +194 -0
  65. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/context_budget.json +27 -0
  66. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/context_compaction.json +27 -0
  67. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/edit_file.json +27 -0
  68. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/index.json +66 -0
  69. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/long_task_planning.json +27 -0
  70. akernel_runtime-0.1.0/src/context_kernel/marketplace_data/skills/multi_file_bugfix.json +28 -0
  71. akernel_runtime-0.1.0/src/context_kernel/memory.py +515 -0
  72. akernel_runtime-0.1.0/src/context_kernel/models.py +144 -0
  73. akernel_runtime-0.1.0/src/context_kernel/planner.py +155 -0
  74. akernel_runtime-0.1.0/src/context_kernel/policy.py +271 -0
  75. akernel_runtime-0.1.0/src/context_kernel/project.py +317 -0
  76. akernel_runtime-0.1.0/src/context_kernel/providers.py +1264 -0
  77. akernel_runtime-0.1.0/src/context_kernel/report_costs.py +375 -0
  78. akernel_runtime-0.1.0/src/context_kernel/runner.py +78 -0
  79. akernel_runtime-0.1.0/src/context_kernel/skills.py +318 -0
  80. akernel_runtime-0.1.0/src/context_kernel/state_writer.py +108 -0
  81. akernel_runtime-0.1.0/src/context_kernel/storage.py +171 -0
  82. akernel_runtime-0.1.0/src/context_kernel/tasks.py +549 -0
  83. akernel_runtime-0.1.0/src/context_kernel/text.py +42 -0
  84. akernel_runtime-0.1.0/src/context_kernel/tokenizer.py +22 -0
  85. akernel_runtime-0.1.0/src/context_kernel/tools.py +544 -0
  86. akernel_runtime-0.1.0/src/context_kernel/verifier.py +77 -0
  87. akernel_runtime-0.1.0/tests/test_runtime.py +2232 -0
  88. akernel_runtime-0.1.0/wake.cmd +4 -0
  89. akernel_runtime-0.1.0/wake.ps1 +68 -0
@@ -0,0 +1,4 @@
1
+ CONTEXT_KERNEL_OPENAI_API_KEY=replace-with-your-key
2
+ CONTEXT_KERNEL_OPENAI_BASE_URL=https://clarmy.cloud/v1
3
+ CONTEXT_KERNEL_OPENAI_MODEL=gpt-5.5
4
+ CONTEXT_KERNEL_OPENAI_AUX_MODEL=gpt-5.3-codex
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: Bug report
3
+ about: Report a reproducible problem in Context Kernel
4
+ title: "[Bug]: "
5
+ labels: bug
6
+ assignees: ""
7
+ ---
8
+
9
+ ## What Happened
10
+
11
+ Describe the problem.
12
+
13
+ ## Reproduction
14
+
15
+ ```powershell
16
+ # commands here
17
+ ```
18
+
19
+ ## Expected Behavior
20
+
21
+ What should have happened?
22
+
23
+ ## Environment
24
+
25
+ - OS:
26
+ - Python version:
27
+ - Context Kernel version or commit:
28
+ - Provider, if relevant:
29
+
30
+ ## Logs Or Reports
31
+
32
+ Attach minimal relevant output, trace ids, eval reports, or benchmark reports.
33
+
34
+ Please redact API keys, private paths, provider responses containing secrets, and local `.akernel` state.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: Feature request
3
+ about: Propose an improvement to the runtime, CLI, docs, or benchmarks
4
+ title: "[Feature]: "
5
+ labels: enhancement
6
+ assignees: ""
7
+ ---
8
+
9
+ ## Problem
10
+
11
+ What context, memory, tool, cost, or workflow problem should this solve?
12
+
13
+ ## Proposed Direction
14
+
15
+ Describe the smallest useful version of the feature.
16
+
17
+ ## Evidence
18
+
19
+ Include traces, evals, benchmarks, examples, or prior art if available.
20
+
21
+ ## Tradeoffs
22
+
23
+ What could this make more complex, slower, or harder to inspect?
@@ -0,0 +1,13 @@
1
+ ## Summary
2
+
3
+ -
4
+
5
+ ## Validation
6
+
7
+ - [ ] `python -m unittest discover -s tests -p test_runtime.py`
8
+ - [ ] `python -m build`
9
+ - [ ] Relevant `akernel eval` or `akernel bench` command, if behavior or token cost changed
10
+
11
+ ## Notes
12
+
13
+ Mention any migration impact, known limitation, or follow-up work.
@@ -0,0 +1,76 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ test-and-smoke:
12
+ name: Test and Smoke (${{ matrix.os }}, py${{ matrix.python-version }})
13
+ runs-on: ${{ matrix.os }}
14
+ strategy:
15
+ fail-fast: false
16
+ matrix:
17
+ os: [ubuntu-latest, windows-latest]
18
+ python-version: ["3.10", "3.12"]
19
+
20
+ steps:
21
+ - name: Checkout
22
+ uses: actions/checkout@v4
23
+
24
+ - name: Set up Python
25
+ uses: actions/setup-python@v5
26
+ with:
27
+ python-version: ${{ matrix.python-version }}
28
+
29
+ - name: Install package
30
+ run: |
31
+ python -m pip install --upgrade pip
32
+ python -m pip install -e .[dev]
33
+
34
+ - name: Run unit tests
35
+ run: python -m unittest discover -s tests -p test_runtime.py
36
+
37
+ - name: CLI smoke
38
+ run: |
39
+ python -m context_kernel init .sandbox-ci
40
+ python -m context_kernel --workspace .sandbox-ci skill register examples/skills/edit_file.json
41
+ python -m context_kernel --workspace .sandbox-ci skill register examples/skills/context_budget.json
42
+ python -m context_kernel --workspace .sandbox-ci memory add --kind preference --text "Prefer CLI-first context budget prototypes." --tags cli
43
+ python -m context_kernel --workspace .sandbox-ci bench run examples/benchmarks/phase2
44
+ python -m context_kernel --workspace .sandbox-ci bench gate examples/benchmarks/phase2 --require-baseline
45
+
46
+ - name: Build package
47
+ if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
48
+ run: python -m build
49
+
50
+ windows-wake:
51
+ name: Windows Wake Flow
52
+ runs-on: windows-latest
53
+
54
+ steps:
55
+ - name: Checkout
56
+ uses: actions/checkout@v4
57
+
58
+ - name: Set up Python
59
+ uses: actions/setup-python@v5
60
+ with:
61
+ python-version: "3.12"
62
+
63
+ - name: Run setup wrapper
64
+ shell: cmd
65
+ run: setup.cmd -Verify
66
+
67
+ - name: Run wake wrapper
68
+ shell: cmd
69
+ run: wake.cmd -InitWorkspace -Workspace .sandbox-wake
70
+
71
+ - name: Validate wake workspace
72
+ shell: pwsh
73
+ run: |
74
+ if (-not (Test-Path -LiteralPath ".sandbox-wake\.akernel")) {
75
+ throw "wake.cmd did not initialize the workspace."
76
+ }
@@ -0,0 +1,158 @@
1
+ name: Release
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ inputs:
6
+ publish:
7
+ description: "Publish artifacts after validation."
8
+ required: true
9
+ default: "false"
10
+ type: choice
11
+ options:
12
+ - "false"
13
+ - "true"
14
+ push:
15
+ tags:
16
+ - "v*"
17
+
18
+ permissions:
19
+ contents: read
20
+
21
+ jobs:
22
+ python-package:
23
+ name: Build Python Package
24
+ runs-on: ubuntu-latest
25
+
26
+ steps:
27
+ - name: Checkout
28
+ uses: actions/checkout@v4
29
+
30
+ - name: Set up Python
31
+ uses: actions/setup-python@v5
32
+ with:
33
+ python-version: "3.12"
34
+
35
+ - name: Install build tools
36
+ run: |
37
+ python -m pip install --upgrade pip
38
+ python -m pip install build twine
39
+
40
+ - name: Build package
41
+ run: python -m build
42
+
43
+ - name: Check package metadata
44
+ run: python -m twine check dist/*
45
+
46
+ - name: Smoke install wheel
47
+ run: |
48
+ python -m venv .release-smoke
49
+ . .release-smoke/bin/activate
50
+ python -m pip install dist/*.whl
51
+ akernel --help
52
+
53
+ - name: Upload Python artifacts
54
+ uses: actions/upload-artifact@v4
55
+ with:
56
+ name: python-dist
57
+ path: dist/*
58
+
59
+ npm-package:
60
+ name: Pack npm Launcher
61
+ runs-on: ubuntu-latest
62
+
63
+ steps:
64
+ - name: Checkout
65
+ uses: actions/checkout@v4
66
+
67
+ - name: Set up Node
68
+ uses: actions/setup-node@v4
69
+ with:
70
+ node-version: "20"
71
+
72
+ - name: Validate npm package
73
+ working-directory: packages/npm/akernel
74
+ run: npm pack --dry-run
75
+
76
+ benchmark-evidence:
77
+ name: Build Benchmark Evidence
78
+ runs-on: ubuntu-latest
79
+
80
+ steps:
81
+ - name: Checkout
82
+ uses: actions/checkout@v4
83
+
84
+ - name: Set up Python
85
+ uses: actions/setup-python@v5
86
+ with:
87
+ python-version: "3.12"
88
+
89
+ - name: Install package
90
+ run: |
91
+ python -m pip install --upgrade pip
92
+ python -m pip install -e .[dev]
93
+
94
+ - name: Prepare benchmark workspace
95
+ run: |
96
+ python -m context_kernel.cli --workspace .release-bench init .release-bench
97
+ python -m context_kernel.cli --workspace .release-bench skill register examples/skills/edit_file.json
98
+ python -m context_kernel.cli --workspace .release-bench skill register examples/skills/context_budget.json
99
+ python -m context_kernel.cli --workspace .release-bench memory add --kind preference --text "Prefer CLI-first context budget prototypes." --tags cli
100
+
101
+ - name: Run benchmark scale suite
102
+ run: python -m context_kernel.cli --workspace .release-bench bench run examples/benchmarks/scale
103
+
104
+ - name: Export benchmark evidence
105
+ run: python -m context_kernel.cli --workspace .release-bench bench evidence --limit 1 --fail-under 30 --output .release-bench/benchmark-evidence.md
106
+
107
+ - name: Upload benchmark evidence
108
+ uses: actions/upload-artifact@v4
109
+ with:
110
+ name: benchmark-evidence
111
+ path: |
112
+ .release-bench/benchmark-evidence.md
113
+ .release-bench/benchmarks/*.json
114
+
115
+ publish-pypi:
116
+ name: Publish To PyPI
117
+ runs-on: ubuntu-latest
118
+ needs: [python-package, npm-package, benchmark-evidence]
119
+ if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true')
120
+ permissions:
121
+ id-token: write
122
+ contents: read
123
+ environment: pypi
124
+
125
+ steps:
126
+ - name: Download Python artifacts
127
+ uses: actions/download-artifact@v4
128
+ with:
129
+ name: python-dist
130
+ path: dist
131
+
132
+ - name: Publish Python package
133
+ uses: pypa/gh-action-pypi-publish@release/v1
134
+
135
+ publish-npm:
136
+ name: Publish npm Launcher
137
+ runs-on: ubuntu-latest
138
+ needs: [python-package, npm-package, benchmark-evidence]
139
+ if: (startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true')) && vars.PUBLISH_NPM == 'true'
140
+ permissions:
141
+ contents: read
142
+ environment: npm
143
+
144
+ steps:
145
+ - name: Checkout
146
+ uses: actions/checkout@v4
147
+
148
+ - name: Set up Node
149
+ uses: actions/setup-node@v4
150
+ with:
151
+ node-version: "20"
152
+ registry-url: "https://registry.npmjs.org"
153
+
154
+ - name: Publish npm package
155
+ working-directory: packages/npm/akernel
156
+ env:
157
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
158
+ run: npm publish --access public
@@ -0,0 +1,65 @@
1
+ # Changelog
2
+
3
+ All notable changes to Context Kernel will be recorded in this file.
4
+
5
+ The project follows a pragmatic pre-1.0 changelog: breaking changes may occur, but they should be documented with migration notes when possible.
6
+
7
+ ## Unreleased
8
+
9
+ No changes yet.
10
+
11
+ ## 0.1.0 - 2026-05-12
12
+
13
+ ### Added
14
+
15
+ - `akernel` now starts the interactive agent session by default, with `akernel-chat` kept as a compatibility shortcut.
16
+ - `akernel setup` configures project-local OpenAI-compatible provider settings, including primary and auxiliary model names.
17
+ - User-level launchers make `akernel` available from any directory after the Windows setup flow.
18
+ - Interactive chat now exposes richer session status, command palette, current task context, run summaries, cost inspection, paste mode, file attachments, and policy-checked command attachments.
19
+ - Primary and auxiliary model roles are tracked separately, with automatic routing and optional auxiliary review before primary-model steps.
20
+ - Project scanning writes `.akernel/project.json` with detected languages, package managers, key files, local instruction files, safe command roots, and likely test/build commands.
21
+ - Agent verification requests can prefer scanned project commands instead of guessing test, build, lint, or install commands.
22
+ - The agent loop can run a project test command, inspect simple Python failure output, apply a bounded patch, and rerun verification for simple failing-test repairs.
23
+ - The agent action parser can recover valid JSON actions wrapped in extra text or fenced code blocks, while still recording the strict contract miss.
24
+ - Agent runs now include compact failure diagnostics with category, reason, and next-step guidance for configuration, auth, network, endpoint, protocol, budget, policy, command, tool, malformed-action, and loop-guard failures.
25
+ - `memory prune` archives lower-priority active memories by record count or token budget, with dry-run support.
26
+ - `memory global-push` and `memory global-pull` provide explicit cross-project memory sync through a user-level global store.
27
+ - Global memory sync supports dry-run previews, namespaces, source-project filters, tag filters, and provenance tags for controlled cross-project sharing.
28
+ - `skill market-list` and `skill market-install` install packaged skill contracts from the built-in marketplace.
29
+ - Skill marketplace indexes now support v2 metadata with skill versions, licenses, publisher, Context Kernel compatibility checks, file/HTTP(S) indexes, and explicit remote trust gates.
30
+ - Packaged marketplace skills now include multi-file bugfix, long task planning, and context compaction contracts.
31
+ - Release helper scripts and a thin npm launcher wrapper prepare the project for PyPI/npm distribution.
32
+ - Release workflow, PyPI metadata checks, npm package dry-run validation, and npm launcher bootstrap support prepare one-command remote installation.
33
+ - Release workflow now generates and uploads benchmark evidence artifacts alongside publish-ready build checks.
34
+ - Scale benchmark fixtures cover context pressure, editing, global memory, and marketplace workflows.
35
+ - `bench evidence` summarizes saved benchmark reports into JSON or Markdown proof pages with aggregate token savings, pass rate, strongest savings, weakest savings, and optional minimum-savings gates.
36
+ - Benchmark evidence documentation records the current deterministic scale snapshot and reproduction commands.
37
+ - Publishing setup documentation lists the PyPI Trusted Publishing, npm token, GitHub environment, and first-release steps needed for public release.
38
+ - Product roadmap documentation defines completion bars for TUI, advanced editing, memory retention, marketplace, distribution, and benchmark maturity.
39
+ - `akernel --ui auto|classic|tui` adds a zero-dependency full-screen terminal UI with transcript, session sidebar, last-run summary, diagnostics, pending context, and input hint.
40
+ - The TUI now uses a cockpit layout with a status header, command strip, task mission panel, model stack, workspace summary, and last-run action timeline.
41
+ - Failing-test recovery can now read multiple file candidates from command output and apply inferred multi-file fixes as one rollback-safe `batch_patch`.
42
+ - Long task sessions can now carry structured milestone plans, active checkpoints, acceptance criteria, and compact resume prompts through `task plan`, `task next`, and `task checkpoint`.
43
+ - `memory audit` and enhanced `memory prune` explain retention scores, token cost, pinned records, and trace-backed recoverability before archiving lower-value memories.
44
+
45
+ ### Changed
46
+
47
+ - The current directory is now the default workspace for bare `akernel`, making the CLI behave more like a project-local coding agent.
48
+ - Agent reports are kept compact by default and point back to authoritative run and tool traces for full audit detail.
49
+ - Common one-tool model output shapes such as `{ "tool": ... }`, `{ "name": ..., "arguments": ... }`, and single OpenAI-style `tool_calls` are normalized into the canonical action contract.
50
+
51
+ ### Initial Alpha Baseline
52
+
53
+ - CLI workspace initialization with `.akernel` local state.
54
+ - Structured memory storage with typed records.
55
+ - Skill registry with progressive contract loading.
56
+ - Context assembly, budget profiles, and token pressure reports.
57
+ - Mock and OpenAI-compatible providers.
58
+ - Policy checks for file and command operations.
59
+ - Policy-gated local tools for read, write, patch, batch patch, delete, and command execution.
60
+ - Resumable task sessions with compact task briefs.
61
+ - Bounded agent loop with tool planning, recovery reads, compact saved reports, and agent cost reports.
62
+ - Eval and benchmark runners with cost reports, diffs, and regression gates.
63
+ - `bench gate` for one-command benchmark validation.
64
+ - Windows setup and wake wrappers.
65
+ - CI workflow for tests, packaging, CLI smoke, benchmark gate, and Windows wake validation.
@@ -0,0 +1,24 @@
1
+ # Code Of Conduct
2
+
3
+ Context Kernel is a technical project, but the work is still human work. We want discussion to stay rigorous, generous, and useful.
4
+
5
+ ## Expected Behavior
6
+
7
+ - Be direct about technical concerns without making them personal.
8
+ - Assume good intent while still asking for evidence.
9
+ - Welcome newcomers and explain project context when it helps.
10
+ - Keep criticism specific, actionable, and grounded in code, docs, traces, or benchmarks.
11
+ - Respect boundaries around private data, credentials, and unpublished work.
12
+
13
+ ## Unacceptable Behavior
14
+
15
+ - Harassment, threats, or personal attacks.
16
+ - Dismissive comments about someone's background, identity, language, or experience level.
17
+ - Publishing private information, secrets, or credentials.
18
+ - Repeatedly derailing issues or pull requests away from the project goal.
19
+
20
+ ## Enforcement
21
+
22
+ Maintainers may edit, hide, or remove comments; close issues; reject contributions; or block participants when behavior harms the project or its contributors.
23
+
24
+ If you need to report a conduct concern, open a GitHub issue asking for a maintainer contact path without sharing private details publicly.
@@ -0,0 +1,56 @@
1
+ # Contributing To Context Kernel
2
+
3
+ Thank you for helping make agent runtimes more inspectable, testable, and token-disciplined.
4
+
5
+ Context Kernel is early alpha software, so the best contributions are small, well-tested, and easy to reason about.
6
+
7
+ ## Development Setup
8
+
9
+ ```powershell
10
+ python -m pip install -e .[dev]
11
+ python -m unittest discover -s tests -p test_runtime.py
12
+ ```
13
+
14
+ On Windows, the easiest local path is:
15
+
16
+ ```powershell
17
+ .\setup.cmd
18
+ .\wake.cmd
19
+ ```
20
+
21
+ ## Contribution Principles
22
+
23
+ - Keep context spending visible. New routing, memory, skill, or agent behavior should expose enough trace data to explain token use.
24
+ - Prefer structured state over prompt text. Avoid adding long natural-language instructions when runtime data structures can carry the same meaning.
25
+ - Preserve policy boundaries. File edits, shell commands, and provider execution should stay behind explicit checks.
26
+ - Add benchmarks for optimizations. Token savings claims should be backed by eval or benchmark output.
27
+ - Keep dependencies boring. Add a dependency only when it clearly reduces complexity or enables a capability the standard library cannot reasonably provide.
28
+
29
+ ## Pull Request Checklist
30
+
31
+ - Tests pass with `python -m unittest discover -s tests -p test_runtime.py`.
32
+ - CLI behavior is documented when command output or flags change.
33
+ - New token-sensitive behavior includes an eval, benchmark, trace, or cost-report check.
34
+ - No secrets, `.env`, local `.akernel` state, build artifacts, or virtualenv files are committed.
35
+ - User-facing errors are concise and actionable.
36
+
37
+ ## Useful Local Checks
38
+
39
+ ```powershell
40
+ python -m pip check
41
+ python -m unittest discover -s tests -p test_runtime.py
42
+ python -m build
43
+ akernel --workspace .sandbox bench gate examples\benchmarks\phase2 --require-baseline
44
+ ```
45
+
46
+ ## Issue Triage
47
+
48
+ When opening an issue, include:
49
+
50
+ - the command you ran
51
+ - the expected behavior
52
+ - the actual behavior
53
+ - relevant OS and Python version
54
+ - a minimal fixture, trace id, or benchmark report if available
55
+
56
+ Please redact API keys, provider responses containing secrets, and private project paths before sharing logs.
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ https://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. Do not include
183
+ the brackets. The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 Context Kernel contributors
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ https://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,18 @@
1
+ include README.md
2
+ include LICENSE
3
+ include NOTICE
4
+ include CONTRIBUTING.md
5
+ include SECURITY.md
6
+ include CODE_OF_CONDUCT.md
7
+ include CHANGELOG.md
8
+ include .env.example
9
+ include setup.ps1
10
+ include wake.ps1
11
+ include setup.cmd
12
+ include wake.cmd
13
+ recursive-include .github *.md *.yml
14
+ recursive-include docs *.md
15
+ recursive-include examples *.json *.md
16
+ recursive-include scripts *.ps1
17
+ recursive-include packages *.json *.js *.md
18
+ recursive-include tests *.py