@alessandroraffa/tangyr 0.0.2 → 0.10.0

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.
@@ -0,0 +1,46 @@
1
+ # mappings/
2
+
3
+ Declarative translation inputs for `tangyr`.
4
+
5
+ These files are part of the canonical runtime bundle, but they are design-time metadata rather than user-facing runtime artifacts. They define the current active v1 translation baseline for:
6
+
7
+ - `Claude Code`
8
+ - `GitHub Copilot`
9
+ - `Codex`
10
+ - `OpenCode` — full six-slot profile: `instructions` (`AGENTS.md` at the XDG-based `~/.config/opencode/` path), `agents`, `commands`, `skills` (OpenCode-local), `skills_shared` (cross-tool `~/.agents/skills`), and `config_doc` (`opencode.json`)
11
+ - `Cursor` — full eight-slot profile: `instructions` (`AGENTS.md` at `~/.cursor/rules/`), `agents` (`~/.cursor/agents/`), `rules` (`~/.cursor/rules/`), `skills` (Cursor-local `~/.cursor/skills/`), `skills_shared` (cross-tool `~/.agents/skills`), `hooks_file` (`~/.cursor/hooks.json`), `mcp_file` (`~/.cursor/mcp.json`), and `permissions_file` (`~/.cursor/permissions.json`)
12
+ - `Cline` — five-slot profile: `instructions` (`AGENTS.md` at project root — project scope only; global `instructions` is `null` because Cline has no documented global `AGENTS.md` read location and the global custom-instructions field is interface-only), `rules` (project: `.clinerules/`; global: `~/Documents/Cline/Rules` — macOS primary), `workflows` (project: `.clinerules/workflows/`; global: `~/Documents/Cline/Workflows/`), `skills` (project: `.cline/skills/`; global: `~/.cline/skills/`), and `mcp_file` (project: `cline-mcp.json`; global: `~/.cline/mcp.json`)
13
+
14
+ The files here intentionally distinguish between:
15
+
16
+ - observed canonical source shape in the current bundle
17
+ - planned source fields inherited from target-state design documents
18
+ - adapter policy that still requires runtime probe or target-specific resolution
19
+
20
+ When a vendor contract is not one-to-one, these mappings prefer capability classes and delivery policy over hard-coded literal field tokens.
21
+
22
+ ## model-tiers.yaml — custom_provider block
23
+
24
+ `model-tiers.yaml` carries an optional top-level `custom_provider` block (parallel to `tiers`). When present, it declares the single canonical custom-provider that the tool emits across the six targets. The block has the following fields:
25
+
26
+ | Field | Type | Required | Description |
27
+ | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
28
+ | `id` | string | yes | Provider identifier; becomes the key under `provider.<id>` in OpenCode and the TOML section ID in Codex |
29
+ | `name` | string | yes | Display name for the provider |
30
+ | `base_url` | string | yes | Provider-level base URL |
31
+ | `api_key_env` | string | yes | Environment-variable name holding the API key (never an inline secret value) |
32
+ | `wire_api` | string | no | Discriminator: `"responses"` = OpenAI Responses API; absent or any other value = chat-completions only |
33
+ | `models` | array | yes | Non-empty array of model entries (see below) |
34
+
35
+ Each entry in `models` requires:
36
+
37
+ | Field | Type | Required | Description |
38
+ | --------------- | ------ | -------- | ----------------------------- |
39
+ | `id` | string | yes | Model identifier |
40
+ | `name` | string | yes | Display name |
41
+ | `context_limit` | number | yes | Context-window size in tokens |
42
+ | `output_limit` | number | yes | Maximum output tokens |
43
+
44
+ **Fail-closed validation**: a `custom_provider` declaration that omits `context_limit` or `output_limit` on any model entry, or that declares an empty `models` array, causes `loadMappings` to throw immediately with a descriptive error message beginning `custom-provider-limits-missing:`.
45
+
46
+ **`wire_api` semantics**: `"responses"` enables Codex `[model_providers.<id>]` TOML emission and selects `@ai-sdk/openai` as the npm package for OpenCode. When `wire_api` is absent or non-`"responses"`, Codex records a `provider-wire-protocol` loss and OpenCode uses `@ai-sdk/openai-compatible`.
@@ -0,0 +1,87 @@
1
+ version: 1
2
+ status: active
3
+ active_targets:
4
+ - claude-code
5
+ - copilot
6
+ - codex
7
+ - opencode
8
+ - cursor
9
+ - cline
10
+
11
+ notes:
12
+ - "`observed` means the field exists in current files under projects/tangyr/agent-coding/agents/."
13
+ - "`planned` means the field is carried from the target-state design but is not yet observed in current agent files."
14
+ - "Exact vendor literal field names are resolved by the target adapter when the vendor contract is not one-to-one."
15
+
16
+ actions:
17
+ direct: Preserve the field as-is in the target-native representation.
18
+ mapped: Translate the field into the closest target-native representation.
19
+ derive: Compute one or more target-native values from canonical source data.
20
+ drop: Omit the field and record semantic loss.
21
+ external-bridge: Deliver the capability through another managed surface, not inside the target agent artifact.
22
+
23
+ fields:
24
+ name:
25
+ source_status: observed
26
+ claude-code: direct
27
+ copilot: mapped
28
+ codex: mapped
29
+
30
+ description:
31
+ source_status: observed
32
+ claude-code: direct
33
+ copilot: mapped
34
+ codex: mapped
35
+
36
+ tools:
37
+ source_status: observed
38
+ claude-code: direct
39
+ copilot: mapped
40
+ codex: derive
41
+ notes:
42
+ - Copilot keeps tool intent through its custom-agent surface when supported by the adapter.
43
+ - Codex uses tool intent primarily to derive sandbox and approval posture rather than a one-to-one tools list.
44
+
45
+ model:
46
+ source_status: observed
47
+ claude-code: direct
48
+ copilot: mapped
49
+ codex: mapped
50
+
51
+ skills:
52
+ source_status: observed
53
+ claude-code: direct
54
+ copilot: drop
55
+ codex: external-bridge
56
+ notes:
57
+ - Codex skills are delivered through the user-level bridge path rather than embedded in the TOML agent artifact.
58
+
59
+ permissionMode:
60
+ source_status: planned
61
+ claude-code: direct
62
+ copilot: drop
63
+ codex: derive
64
+
65
+ disallowedTools:
66
+ source_status: planned
67
+ claude-code: direct
68
+ copilot: drop
69
+ codex: drop
70
+
71
+ maxTurns:
72
+ source_status: planned
73
+ claude-code: direct
74
+ copilot: drop
75
+ codex: drop
76
+
77
+ hooks:
78
+ source_status: planned
79
+ claude-code: direct
80
+ copilot: drop
81
+ codex: drop
82
+
83
+ mcpServers:
84
+ source_status: planned
85
+ claude-code: direct
86
+ copilot: drop
87
+ codex: drop
@@ -0,0 +1,114 @@
1
+ version: 1
2
+ status: active
3
+ active_targets:
4
+ - claude-code
5
+ - copilot
6
+ - codex
7
+ - opencode
8
+ - cursor
9
+ - cline
10
+
11
+ notes:
12
+ - Source events below are the events currently observed in the canonical agent-coding kit at projects/tangyr/agent-coding/hooks/hooks.json.
13
+ - Copilot event coverage must still be runtime-probed because official pages do not expose a single stable denominator.
14
+ - Codex hook support is currently a macOS/Linux baseline; Windows remains unsupported unless vendor documentation changes.
15
+
16
+ source_events:
17
+ - PreToolUse
18
+ - PostToolUse
19
+ - PreCompact
20
+ - SubagentStart
21
+ - SubagentStop
22
+ - Stop
23
+
24
+ targets:
25
+ claude-code:
26
+ delivery: native-merge
27
+ source_to_target:
28
+ PreToolUse: PreToolUse
29
+ PostToolUse: PostToolUse
30
+ PreCompact: PreCompact
31
+ SubagentStart: SubagentStart
32
+ SubagentStop: SubagentStop
33
+ Stop: Stop
34
+
35
+ copilot:
36
+ delivery: mapped
37
+ requires_probe: true
38
+ source_to_target:
39
+ PreToolUse:
40
+ status: mapped
41
+ target_event: preToolUse
42
+ PostToolUse:
43
+ status: mapped
44
+ target_event: postToolUse
45
+ PreCompact:
46
+ status: drop
47
+ severity: warning
48
+ reason: No documented user-level equivalent in the active baseline.
49
+ SubagentStart:
50
+ status: probe
51
+ reason: The runtime may expose a related event, but the adapter must not hard-code it as baseline support.
52
+ SubagentStop:
53
+ status: probe
54
+ reason: The runtime may expose a related event, but the adapter must not hard-code it as baseline support.
55
+ Stop:
56
+ status: mapped
57
+ target_event: sessionEnd
58
+ severity: warning
59
+ reason: Closest documented session-end lifecycle event, not a one-to-one semantic equivalent.
60
+
61
+ codex:
62
+ delivery: partial
63
+ supported_platforms:
64
+ macos: true
65
+ linux: true
66
+ windows: false
67
+ source_to_target:
68
+ PreToolUse:
69
+ status: mapped
70
+ target_event: PreToolUse
71
+ PostToolUse:
72
+ status: mapped
73
+ target_event: PostToolUse
74
+ PreCompact:
75
+ status: drop
76
+ severity: warning
77
+ reason: No documented equivalent in the current baseline.
78
+ SubagentStart:
79
+ status: drop
80
+ severity: warning
81
+ reason: No documented equivalent in the current baseline.
82
+ SubagentStop:
83
+ status: drop
84
+ severity: warning
85
+ reason: No documented equivalent in the current baseline.
86
+ Stop:
87
+ status: mapped
88
+ target_event: Stop
89
+
90
+ cursor:
91
+ delivery: native-versioned-object
92
+ source_to_target:
93
+ PreToolUse:
94
+ status: mapped
95
+ target_event: PreToolUse
96
+ PostToolUse:
97
+ status: mapped
98
+ target_event: PostToolUse
99
+ PreCompact:
100
+ status: drop
101
+ severity: warning
102
+ reason: No documented equivalent in the Cursor hooks baseline.
103
+ SubagentStart:
104
+ status: drop
105
+ severity: warning
106
+ reason: No documented equivalent in the Cursor hooks baseline.
107
+ SubagentStop:
108
+ status: drop
109
+ severity: warning
110
+ reason: No documented equivalent in the Cursor hooks baseline.
111
+ Stop:
112
+ status: drop
113
+ severity: warning
114
+ reason: No documented equivalent in the Cursor hooks baseline.
@@ -0,0 +1,39 @@
1
+ version: 1
2
+ status: active
3
+ active_targets: [claude-code, copilot, codex]
4
+
5
+ entry_types:
6
+ command-as-skill: info
7
+ rule-as-instruction: info
8
+ rule-mode-downgrade: warning
9
+ rule-path-scoping: warning
10
+ hook-event-drop: warning
11
+ hook-as-plugin: error
12
+ instructions-shim: info
13
+ permission-coarsening: error
14
+ provider-not-representable: error
15
+ provider-wire-protocol: error
16
+ model-not-representable: error
17
+ persona-not-representable: error
18
+ settings-not-representable: warning
19
+
20
+ severity_levels:
21
+ info:
22
+ meaning: Target materialization differs in form but not in intended operational meaning.
23
+ examples:
24
+ - File extension or container format changes with no functional loss.
25
+ - A capability is delivered through a bridge path instead of the source artifact itself.
26
+
27
+ warning:
28
+ meaning: Target materialization preserves useful behavior but narrows semantics or lifecycle coverage.
29
+ examples:
30
+ - Hook coverage drops to a documented subset of the source event model.
31
+ - A stop-like lifecycle event is approximated by a session-end event.
32
+ - A field survives only as freeform instructions rather than structured metadata.
33
+
34
+ error:
35
+ meaning: A critical control, enforcement property, or safety boundary does not survive translation.
36
+ examples:
37
+ - Permission or sandbox intent cannot be enforced on the target.
38
+ - A target lacks any supported equivalent for a required managed surface.
39
+ - A shared-file mutation would require modifying ownership beyond the managed boundary.
@@ -0,0 +1,59 @@
1
+ version: 1
2
+ status: active
3
+ active_targets:
4
+ - claude-code
5
+ - copilot
6
+ - codex
7
+ - opencode
8
+ - cursor
9
+ - cline
10
+
11
+ notes:
12
+ - The canonical values below are normalized tiers, not a promise of vendor-specific literal model IDs.
13
+ - Current observed canonical values in the bundle are `opus` and `sonnet`.
14
+ - codex_reasoning_effort carries reasoning-intent guidance; codex_model carries the resolved OpenAI model ID emitted into compiled TOML.
15
+ - The custom_provider block carries the §10 canonical custom-provider declaration. wire_api: responses enables Codex emission and selects @ai-sdk/openai for OpenCode. Absence of wire_api means chat-completions only — Codex records provider-wire-protocol loss; OpenCode uses @ai-sdk/openai-compatible.
16
+
17
+ tiers:
18
+ opus:
19
+ source_status: observed
20
+ class: flagship
21
+ claude-code: preserve
22
+ copilot: preserve-if-supported
23
+ codex_reasoning_effort: high
24
+ codex_model: gpt-5.5
25
+ opencode: preserve
26
+ cursor: preserve
27
+ cline: preserve
28
+ sonnet:
29
+ source_status: observed
30
+ class: balanced
31
+ claude-code: preserve
32
+ copilot: preserve-if-supported
33
+ codex_reasoning_effort: medium
34
+ codex_model: gpt-5.4
35
+ opencode: preserve
36
+ cursor: preserve
37
+ cline: preserve
38
+ haiku:
39
+ source_status: planned
40
+ class: fast
41
+ claude-code: preserve
42
+ copilot: preserve-if-supported
43
+ codex_reasoning_effort: low
44
+ codex_model: gpt-5.4-mini
45
+ opencode: preserve
46
+ cursor: preserve
47
+ cline: preserve
48
+
49
+ custom_provider:
50
+ id: "custom-provider"
51
+ name: "Custom Provider"
52
+ base_url: "https://api.example.com/v1"
53
+ api_key_env: "CUSTOM_PROVIDER_API_KEY"
54
+ wire_api: "responses"
55
+ models:
56
+ - id: "custom-model"
57
+ name: "Custom Model"
58
+ context_limit: 200000
59
+ output_limit: 65536
@@ -0,0 +1,22 @@
1
+ version: 1
2
+ status: active
3
+ active_targets: [claude-code, copilot, codex]
4
+
5
+ notes:
6
+ - No current agent file in projects/tangyr/agent-coding/agents/ declares `permissionMode`.
7
+ - This file exists because the target-state design expects permission intent to become an explicit canonical field later.
8
+ - Until that field exists in source artifacts, adapters must treat this file as reserved mapping policy rather than active input.
9
+
10
+ canonical_permission_modes:
11
+ read-only:
12
+ claude-code: direct
13
+ copilot: drop
14
+ codex: derive
15
+ workspace-write:
16
+ claude-code: direct
17
+ copilot: drop
18
+ codex: derive
19
+ plan:
20
+ claude-code: direct
21
+ copilot: drop
22
+ codex: derive
@@ -0,0 +1,131 @@
1
+ version: 1
2
+ status: active
3
+ active_targets:
4
+ - claude-code
5
+ - copilot
6
+ - codex
7
+ - opencode
8
+ - cursor
9
+ - cline
10
+
11
+ notes:
12
+ - Paths here describe the v1 contract for both global (user-level) and project scope.
13
+ - Global values expand ~ and $VSCODE_USER_DATA at resolve time.
14
+ - Project values are relative to the project root; they must not be absolute paths.
15
+ - A global value of null marks a project-only slot (no runtime equivalent at user level).
16
+
17
+ targets:
18
+ claude-code:
19
+ global:
20
+ instructions: ~/.claude/AGENTS.md
21
+ instructions_shim: ~/.claude/CLAUDE.md
22
+ agents: ~/.claude/agents
23
+ skills: ~/.claude/skills
24
+ commands: ~/.claude/commands
25
+ rules: ~/.claude/rules
26
+ output_styles: ~/.claude/output-styles
27
+ hooks_shared_file: ~/.claude/settings.json
28
+ settings_shared_file: ~/.claude/settings.json
29
+ mcp_shared_file: ~/.claude.json
30
+ hooks: ~/.agents/hooks
31
+ project:
32
+ instructions: AGENTS.md
33
+ instructions_shim: CLAUDE.md
34
+ agents: .claude/agents
35
+ skills: .claude/skills
36
+ commands: .claude/commands
37
+ rules: .claude/rules
38
+ output_styles: .claude/output-styles
39
+ hooks_shared_file: .claude/settings.json
40
+ settings_shared_file: .claude/settings.json
41
+ mcp_shared_file: .claude.json
42
+ hooks: .agents/hooks
43
+
44
+ copilot:
45
+ global:
46
+ agents: $VSCODE_USER_DATA/agents
47
+ skills: ~/.copilot/skills
48
+ prompts: $VSCODE_USER_DATA/prompts
49
+ hooks: ~/.copilot/hooks
50
+ mcp_shared_file: ~/.copilot/mcp-config.json
51
+ instructions: null
52
+ project:
53
+ agents: .github/agents
54
+ skills: .github/skills
55
+ prompts: .github/prompts
56
+ hooks: .github/hooks
57
+ mcp_shared_file: .vscode/mcp.json
58
+ instructions: .github/copilot-instructions.md
59
+ agents_md: AGENTS.md
60
+
61
+ codex:
62
+ global:
63
+ instructions: ~/.codex/AGENTS.md
64
+ agents: ~/.codex/agents
65
+ rules: ~/.codex/rules
66
+ skills: ~/.agents/skills
67
+ hooks_shared_file: ~/.codex/hooks.json
68
+ mcp_shared_file: ~/.codex/config.toml
69
+ project:
70
+ instructions: AGENTS.md
71
+ agents: .codex/agents
72
+ rules: .codex/rules
73
+ skills: .codex/skills
74
+ hooks_shared_file: .codex/hooks.json
75
+ mcp_shared_file: .codex/config.toml
76
+
77
+ opencode:
78
+ global:
79
+ instructions: ~/.config/opencode/AGENTS.md
80
+ agents: ~/.config/opencode/agents
81
+ commands: ~/.config/opencode/commands
82
+ skills: ~/.config/opencode/skills
83
+ skills_shared: ~/.agents/skills
84
+ config_doc: ~/.config/opencode/opencode.json
85
+ project:
86
+ instructions: AGENTS.md
87
+ agents: .opencode/agents
88
+ commands: .opencode/commands
89
+ skills: .opencode/skills
90
+ skills_shared: .agents/skills
91
+ config_doc: opencode.json
92
+
93
+ cursor:
94
+ global:
95
+ instructions: ~/.cursor/rules/AGENTS.md
96
+ agents: ~/.cursor/agents
97
+ rules: ~/.cursor/rules
98
+ skills: ~/.cursor/skills
99
+ skills_shared: ~/.agents/skills
100
+ hooks_file: ~/.cursor/hooks.json
101
+ mcp_file: ~/.cursor/mcp.json
102
+ permissions_file: ~/.cursor/permissions.json
103
+ project:
104
+ instructions: .cursor/rules/AGENTS.md
105
+ agents: .cursor/agents
106
+ rules: .cursor/rules
107
+ skills: .cursor/skills
108
+ skills_shared: .agents/skills
109
+ hooks_file: .cursor/hooks.json
110
+ mcp_file: .cursor/mcp.json
111
+ permissions_file: .cursor/permissions.json
112
+
113
+ cline:
114
+ global:
115
+ instructions: null
116
+ rules: ~/Documents/Cline/Rules
117
+ workflows: ~/Documents/Cline/Workflows
118
+ skills: ~/.cline/skills
119
+ mcp_file: ~/.cline/mcp.json
120
+ project:
121
+ instructions: AGENTS.md
122
+ rules: .clinerules
123
+ workflows: .clinerules/workflows
124
+ skills: .cline/skills
125
+ mcp_file: cline-mcp.json
126
+
127
+ reserved_source_slots:
128
+ lsp:
129
+ source_path: ./.lsp.json
130
+ status: reserved
131
+ reason: No active global v1 target mapping is currently committed.
@@ -0,0 +1,19 @@
1
+ version: 1
2
+ status: active
3
+ active_targets: [claude-code, copilot, codex]
4
+
5
+ notes:
6
+ - Codex requires an explicit separation between behavioral guidance and execution-policy rules.
7
+ - This file gives the classification vocabulary for that split.
8
+
9
+ canonical_rule_modes:
10
+ guidance:
11
+ description: Behavioral or instructional content that remains meaningful as written guidance.
12
+ claude-code: native-markdown
13
+ copilot: skip-in-global-v1
14
+ codex: append-to-agents
15
+ exec-policy:
16
+ description: Operational restrictions that can be expressed as command execution policy.
17
+ claude-code: native-markdown
18
+ copilot: skip-in-global-v1
19
+ codex: emit-dot-rules
@@ -0,0 +1,107 @@
1
+ version: 1
2
+ status: active
3
+ active_targets:
4
+ - claude-code
5
+ - copilot
6
+ - codex
7
+
8
+ mapping_modes:
9
+ direct: Preserve the canonical literal name.
10
+ capability-map: Translate by capability class instead of by literal token.
11
+ derive-sandbox: Contribute to sandbox or approval derivation rather than a direct emitted tool token.
12
+
13
+ notes:
14
+ - The canonical tool names below are observed in current agent frontmatter.
15
+ - Copilot and Codex adapters should not assume that every canonical tool name has a stable one-to-one emitted literal.
16
+
17
+ canonical_tools:
18
+ Read:
19
+ class: filesystem-read
20
+ claude-code: direct
21
+ copilot: capability-map
22
+ codex: derive-sandbox
23
+ Write:
24
+ class: filesystem-write
25
+ claude-code: direct
26
+ copilot: capability-map
27
+ codex: derive-sandbox
28
+ Edit:
29
+ class: filesystem-write
30
+ claude-code: direct
31
+ copilot: capability-map
32
+ codex: derive-sandbox
33
+ Grep:
34
+ class: repository-search
35
+ claude-code: direct
36
+ copilot: capability-map
37
+ codex: derive-sandbox
38
+ Glob:
39
+ class: repository-search
40
+ claude-code: direct
41
+ copilot: capability-map
42
+ codex: derive-sandbox
43
+ Bash:
44
+ class: shell-execution
45
+ claude-code: direct
46
+ copilot: capability-map
47
+ codex: derive-sandbox
48
+ Agent:
49
+ class: delegation
50
+ claude-code: direct
51
+ copilot: capability-map
52
+ codex: derive-sandbox
53
+ WebSearch:
54
+ class: web-research
55
+ claude-code: direct
56
+ copilot: capability-map
57
+ codex: derive-sandbox
58
+ read/readFile:
59
+ class: filesystem-read
60
+ claude-code: direct
61
+ copilot: capability-map
62
+ codex: derive-sandbox
63
+ edit/newFile:
64
+ class: filesystem-write
65
+ claude-code: direct
66
+ copilot: capability-map
67
+ codex: derive-sandbox
68
+ edit/editFile:
69
+ class: filesystem-write
70
+ claude-code: direct
71
+ copilot: capability-map
72
+ codex: derive-sandbox
73
+ search/textSearch:
74
+ class: repository-search
75
+ claude-code: direct
76
+ copilot: capability-map
77
+ codex: derive-sandbox
78
+ search/fileSearch:
79
+ class: repository-search
80
+ claude-code: direct
81
+ copilot: capability-map
82
+ codex: derive-sandbox
83
+ terminal/runCommand:
84
+ class: shell-execution
85
+ claude-code: direct
86
+ copilot: capability-map
87
+ codex: derive-sandbox
88
+ webresearch/search_google:
89
+ class: web-research
90
+ claude-code: direct
91
+ copilot: capability-map
92
+ codex: derive-sandbox
93
+ web/fetch:
94
+ class: web-research
95
+ claude-code: direct
96
+ copilot: capability-map
97
+ codex: derive-sandbox
98
+ web/githubRepo:
99
+ class: web-research
100
+ claude-code: direct
101
+ copilot: capability-map
102
+ codex: derive-sandbox
103
+ webresearch/visit_page:
104
+ class: web-research
105
+ claude-code: direct
106
+ copilot: capability-map
107
+ codex: derive-sandbox