taskchef 7.27.2 → 7.28.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.2",
+  "version": "7.28.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.2",
+  "version": "7.28.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -37,6 +37,7 @@
     "docs/images/reported-work-duration-mobile.jpg",
     "index.js",
     "mcp",
+    "scripts/roles",
     "scripts/benchmark-dispatch-prepare.js",
     "scripts/e2e-benchmark.js",
     "src",

package/scripts/roles/resolve_roles.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Read native Codex agent preferences without applying their instruction layers.
+
+Requires Python 3.11+. Standalone, standard library only. TaskChef packages an
+identical copy; neither installation imports the other at runtime.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import tomllib
+
+ROLES = ('planner', 'implementer', 'reviewer')
+EFFORTS = ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra')
+
+
+def read_layer(directory):
+    found = {}
+    problems = []
+    try:
+        with os.scandir(directory) as entries:
+            files = sorted(Path(entry.path) for entry in entries if entry.name.endswith('.toml'))
+        for file in files:
+            try:
+                if file.stat().st_size > 65536:
+                    raise ValueError('profile exceeds 64 KiB')
+                with file.open('rb') as stream:
+                    data = tomllib.load(stream)
+                name = data.get('name')
+                if name not in ROLES:
+                    if file.stem in ROLES:
+                        raise ValueError('name must match the role filename')
+                    continue
+                errors = []
+                for field in ('description', 'developer_instructions'):
+                    if not isinstance(data.get(field), str) or not data[field].strip():
+                        errors.append(f'{field} must be a nonempty string')
+                model = data.get('model')
+                effort = data.get('model_reasoning_effort')
+                entry = {'source': str(file), 'model': model, 'effort': effort, 'problems': errors}
+                if name in found:
+                    entry['problems'].append('duplicate role name in the same directory')
+                found[name] = entry
+            except (OSError, ValueError) as error:
+                # Do not expose TOML lines, which can contain unrelated private data.
+                message = f'{file}: unreadable or malformed agent TOML ({type(error).__name__})'
+                problems.append(message)
+                if file.stem in ROLES:
+                    found[file.stem] = {'source': str(file), 'model': None, 'effort': None, 'problems': [message]}
+    except FileNotFoundError:
+        return found, problems
+    except OSError:
+        message = f'{directory}: cannot read agent directory'
+        problems.append(message)
+        found = {role: {'source': str(directory), 'model': None, 'effort': None, 'problems': [message]} for role in ROLES}
+    return found, problems
+
+
+def resolve(project=None, codex_home=None, explicit_model=None, explicit_effort=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    personal, problems = read_layer(home / 'agents')
+    local, local_problems = read_layer(Path(project).resolve() / '.codex' / 'agents') if project else ({}, [])
+    problems += local_problems
+    catalog = None
+    catalog_source = str(home / 'models_cache.json')
+    try:
+        cache = json.loads(Path(catalog_source).read_text())
+        if not isinstance(cache, dict) or not isinstance(cache.get('models'), list):
+            raise ValueError('invalid catalog')
+        for model in cache['models']:
+            if not isinstance(model, dict) or not isinstance(model.get('slug'), str):
+                raise ValueError('invalid model entry')
+            levels = model.get('supported_reasoning_levels')
+            if not isinstance(levels, list) or any(not isinstance(level, dict) or not isinstance(level.get('effort'), str) for level in levels):
+                raise ValueError('invalid effort catalog')
+        catalog = {model['slug']: model for model in cache['models']}
+    except FileNotFoundError:
+        pass
+    except (OSError, ValueError, KeyError, TypeError):
+        problems.append('Local Codex model catalog is unreadable or malformed; validate availability with the current native tool.')
+    results = []
+    for role in ROLES:
+        entry = local.get(role, personal.get(role))
+        source = entry['source'] if entry else None
+        model = entry['model'] if entry else None
+        effort = entry['effort'] if entry else None
+        errors = list(entry['problems']) if entry else []
+        if explicit_model is not None:
+            model, effort = explicit_model, explicit_effort
+            effective_source = 'explicit user model choice'
+            errors = []
+        else:
+            effective_source = source
+            if explicit_effort is not None:
+                effort = explicit_effort
+        if model is not None and (not isinstance(model, str) or not model.strip() or len(model) > 256):
+            errors.append('model must be a nonempty string of at most 256 characters')
+        if effort is not None and effort not in EFFORTS:
+            errors.append('reasoning effort is unsupported')
+        status = 'invalid' if errors else 'configured' if (model is not None or effort is not None) else 'missing'
+        availability = 'not checked; native tool must validate before dispatch'
+        if model and not errors and catalog is not None:
+            if model not in catalog:
+                errors.append('model absent from local Codex catalog; confirm against the current native tool before dispatch')
+                status = 'unavailable'
+            else:
+                supported = [v.get('effort') for v in catalog[model].get('supported_reasoning_levels', []) if isinstance(v, dict)]
+                if effort and effort not in supported:
+                    errors.append('effort absent from local model catalog; confirm against the current native tool')
+                    status = 'unavailable'
+                availability = 'present in cached catalog; current native tool is authoritative'
+        overrides = {}
+        if status == 'configured':
+            if model is not None:
+                overrides['model'] = model
+            if effort is not None:
+                overrides['thinking'] = effort
+        results.append({'role': role, 'source': source, 'effectiveSource': effective_source,
+                        'model': model, 'effort': effort, 'status': status,
+                        'availability': availability, 'problems': errors,
+                        'taskOverrides': overrides,
+                        'subagentOverrides': {('reasoning_effort' if k == 'thinking' else k): v for k, v in overrides.items()},
+                        'fallback': 'inherit parent settings' if role == 'reviewer' else 'native new-task default (not guaranteed dispatcher inheritance)'})
+    return {'roles': results, 'problems': problems, 'catalogSource': catalog_source if catalog is not None else None,
+            'precedence': 'explicit user model (and its explicit effort) > project role > personal role > native defaults; explicit effort alone overrides role effort',
+            'scope': 'Model and effort only; agent instructions, tools, permissions, and other TOML keys are not applied by this adapter.'}
+
+
+def setup(role, model, effort, codex_home=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    existing, problems = read_layer(home / 'agents')
+    if role in existing or problems:
+        return {'created': False, 'role': role, 'problems': problems or ['existing role preserved'], 'source': existing.get(role, {}).get('source')}
+    if not model.strip() or len(model) > 256 or effort not in EFFORTS:
+        raise ValueError('invalid model or effort')
+    directory = home / 'agents'
+    directory.mkdir(parents=True, exist_ok=True)
+    target = directory / f'{role}.toml'
+    data = {'name': role, 'description': f'{role.capitalize()} model preferences',
+            'developer_instructions': f'Perform the assigned {role} work within the user\'s requested scope.',
+            'model': model, 'model_reasoning_effort': effort}
+    try:
+        with target.open('x') as stream:
+            stream.write(''.join(f'{key} = {json.dumps(value)}\n' for key, value in data.items()))
+    except FileExistsError:
+        return {'created': False, 'role': role, 'source': str(target), 'problems': ['existing file preserved']}
+    return {'created': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--project')
+    parser.add_argument('--codex-home')
+    parser.add_argument('--role', choices=ROLES)
+    parser.add_argument('--model')
+    parser.add_argument('--effort')
+    parser.add_argument('--setup', action='store_true')
+    args = parser.parse_args()
+    if args.setup:
+        if not (args.role and args.model and args.effort):
+            parser.error('--setup requires --role, --model, and --effort')
+        result = setup(args.role, args.model, args.effort, args.codex_home)
+    else:
+        result = resolve(args.project, args.codex_home, args.model, args.effort)
+        if args.role:
+            result['roles'] = [r for r in result['roles'] if r['role'] == args.role]
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/skills/taskchef-bootstrap/SKILL.md

@@ -56,3 +56,29 @@ For adding, importing, removing, listing, or reindexing projects, read
 [project index](references/project-index.md). Preserve exact canonical local
 Codex project identity and existing curated entries; opening a folder is not
 proof of registration. Completion requires verifying the intended index entry.
+
+## Optional model roles
+
+Offer planner, implementer, and reviewer profiles during setup. Model and effort
+preferences belong in user configuration, never defaults hard-coded in skills.
+If the user provides values, configure them without asking again. Otherwise
+explain the optional profiles and retain native defaults until values are chosen.
+
+Run `python3 <plugin-root>/scripts/roles/resolve_roles.py` to preview personal
+roles. Python 3.11+ is required for this optional helper. Create each requested
+missing profile with:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --setup --role <role> --model <requested-model> --effort <requested-effort>
+```
+
+This authorized role setup may create `$CODEX_HOME/agents/<role>.toml` (default
+`~/.codex/agents/`) outside the dispatcher workspace. Existing definitions,
+including custom filenames, are preserved. Report conflicts and diagnostics;
+never overwrite a custom role. Re-run the preview and check model/effort against
+the available native interface. Missing roles are optional: TaskChef omits
+new-task overrides; reviewers inherit parent settings. Native new-task defaults
+are not guaranteed dispatcher inheritance. Read the delegate's
+[role resolution](../taskchef-delegate/references/model-roles.md) for precedence
+and adapter limits. Open the dashboard's `/#settings` preview to show the
+configured sources, requested effective settings, fallback, and problems.

package/skills/taskchef-delegate/SKILL.md

@@ -49,6 +49,13 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 3. Route against configured project `name`, `description`, and canonical
    `githubRepos`; use `path` only as checkout identity. Require exactly one
    match and an exact native-project path. Ask instead of guessing.
+   Select `planner` for a requested planning assignment and `implementer` for
+   coding work. Use the matched project's `projectModelRoles` from preparation;
+   resolve explicit user choices and follow [model roles](references/model-roles.md).
+   Small coding changes need no separate planning task. For a planning/coding
+   split, the saved plan is the handoff to a separately requested implementation
+   assignment; do not switch models during a turn or coordinate phases automatically.
+   Resolve configuration problems before recording the task.
 4. Build each executor instruction in this exact shape:
 
    - Begin with the actual assignment on the first line and keep its complete

package/skills/taskchef-delegate/references/model-roles.md

@@ -0,0 +1,49 @@
+# Dispatch model roles
+
+Preparation includes personal and per-project model previews. Use the exact
+matched project's preview. Role preferences use native Codex agent TOML under
+`$CODEX_HOME/agents/` (default `~/.codex/agents/`) and that project's
+`.codex/agents/`; they are optional. The resolver requires Python 3.11+.
+
+Select `planner` for a planning assignment or `implementer` for coding. Pass
+its `taskOverrides` as native `model` and `thinking` arguments only after checking
+those values against the current create-task tool's supported model/effort
+choices. A missing role means omit both arguments and use the native new-task
+default. This is not guaranteed to inherit the dispatcher's model.
+
+Explicit user model choices take precedence over the project role, personal
+role, and native defaults. An explicit model without explicit effort omits effort and uses the native
+interface's omission behavior; do not mix in a different role's effort or claim
+a specific effective effort without evidence. Explicit effort
+alone replaces the resolved role effort. Project roles replace personal roles
+as a unit. To resolve explicit choices, or recheck a preview after configuration
+changes, run:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --project <project-path> --role implementer --model <user-model> --effort <user-effort>
+```
+
+Omit flags the user did not specify. Resolve the plugin root from this skill's
+real path, two parents above the skill directory. Do not substitute dispatcher
+paths for the target project or infer model names from skill prose.
+
+Report malformed profiles, duplicate names, unavailable models/efforts, and
+resolver failures. Do not quietly fall back and claim preferences were honored.
+The local model catalog is advisory: explain if a current native tool disproves
+its stale warning. Otherwise resolve the problem or obtain a valid explicit
+choice before task creation. Native creation failures retain normal TaskChef
+failure reporting. A preparation without role fields supports historical
+installations: check role files before deciding that no preferences exist.
+
+Only model and effort are adapted. The native agent file's instructions, tools,
+permissions, and other settings are not applied by create-task arguments. A
+role name in a title is not a native role selector. If the native interface adds
+a role selector, use it only with verified effective settings.
+
+For a plan-to-implementation handoff, a planner assignment can save
+`plans/addition.md` describing a pure addition function and the acceptance
+example `2 + 3 = 5`. A later implementer assignment reads that exact plan,
+implements the function, runs the example, and uses fresh reviewer subagents.
+The dispatcher returns after each creation; it does not wait for or launch
+subsequent phases automatically. A small addition change can instead go
+straight to the implementer.