@orcalang/orca-lang 0.1.13 → 0.1.16

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 (4) hide show
  1. package/dist/tools.js +8 -8
  2. package/dist/tools.js.map +1 -1
  3. package/package.json +1 -1
  4. package/src/tools.ts +8 -8
package/dist/tools.js CHANGED
@@ -2,7 +2,7 @@
2
2
  export const ORCA_TOOLS = [
3
3
  {
4
4
  name: 'parse_machine',
5
- description: 'Parse an Orca machine definition and return its structure as JSON (states, events, transitions, guards, actions, context). Supports single and multi-machine files. Source must use "# machine Name" heading, "## state Name [initial]" for states, and a "## transitions" section with a | Source | Event | Guard | Target | Action | table.',
5
+ description: 'Parse .orca.md source → JSON (states, events, transitions, guards, actions, context). Syntax: # machine Name, ## state Name [initial|final], ## transitions table (| Source | Event | Guard | Target | Action |).',
6
6
  inputSchema: {
7
7
  type: 'object',
8
8
  properties: {
@@ -13,7 +13,7 @@ export const ORCA_TOOLS = [
13
13
  },
14
14
  {
15
15
  name: 'verify_machine',
16
- description: 'Verify an Orca machine definition for structural correctness, completeness, and determinism. Checks that exactly one [initial] state exists, all states are reachable, no deadlocks exist (every non-final state handles all events or has timeouts), and guards on competing transitions are mutually exclusive. Returns structured errors and warnings.',
16
+ description: 'Verify machine structure: checks [initial] presence (exactly one), reachability, no deadlocks, guard determinism. Returns structured errors with codes and suggestions. Run before compile_machine.',
17
17
  inputSchema: {
18
18
  type: 'object',
19
19
  properties: {
@@ -24,7 +24,7 @@ export const ORCA_TOOLS = [
24
24
  },
25
25
  {
26
26
  name: 'compile_machine',
27
- description: 'Compile a verified Orca machine to XState v5 config (TypeScript) or Mermaid stateDiagram-v2. Run verify_machine first to catch errors before compiling.',
27
+ description: 'Compile verified machine to XState v5 TypeScript or Mermaid stateDiagram-v2. Run verify_machine first. target: "xstate" (default) or "mermaid".',
28
28
  inputSchema: {
29
29
  type: 'object',
30
30
  properties: {
@@ -40,7 +40,7 @@ export const ORCA_TOOLS = [
40
40
  },
41
41
  {
42
42
  name: 'generate_machine',
43
- description: 'Generate a draft Orca machine definition from a natural language specification. Automatically chooses between a single-machine or multi-machine design based on the spec: specs that mention a coordinator, orchestrator, or multiple independently-lifecycled sub-processes route to multi-machine; everything else produces a single machine. Returns raw .orca.md source and an is_multi flag. Always call verify_machine on the result next — then refine_machine if there are errors. Requires LLM configuration via environment variables (ANTHROPIC_API_KEY, etc.).',
43
+ description: 'Generate draft .orca.md from natural language spec. Returns source + is_multi flag. Always verify_machine next, then refine_machine if errors. Requires LLM API key (ANTHROPIC_API_KEY, etc.).',
44
44
  inputSchema: {
45
45
  type: 'object',
46
46
  properties: {
@@ -54,7 +54,7 @@ export const ORCA_TOOLS = [
54
54
  },
55
55
  {
56
56
  name: 'generate_actions',
57
- description: 'Generate action scaffold code for an Orca machine in TypeScript, Python, or Go. Includes registration comments and optional test scaffolds. Requires a successfully parsed machine — pass verified .orca.md source.',
57
+ description: 'Generate action scaffold code from verified machine. lang: typescript (default), python, or go. Pass verified .orca.md source. use_llm: true for implementations vs templates. generate_tests: true for test scaffolds.',
58
58
  inputSchema: {
59
59
  type: 'object',
60
60
  properties: {
@@ -78,7 +78,7 @@ export const ORCA_TOOLS = [
78
78
  },
79
79
  {
80
80
  name: 'generate_multi_machine',
81
- description: 'Generate a draft set of coordinated Orca machines from a natural language specification. Returns multiple machine definitions in one .orca.md file (separated by ---). Always call verify_machine on the result next — then refine_machine if there are errors. Requires LLM configuration via environment variables.',
81
+ description: 'Generate coordinated multi-machine .orca.md from spec (machines separated by ---). Use invoke: ChildMachine in states. Always verify_machine next, then refine_machine if errors. Requires LLM API key.',
82
82
  inputSchema: {
83
83
  type: 'object',
84
84
  properties: {
@@ -92,7 +92,7 @@ export const ORCA_TOOLS = [
92
92
  },
93
93
  {
94
94
  name: 'refine_machine',
95
- description: 'Fix verification errors in an Orca machine using an LLM. Loops until the machine is valid or max_iterations is reached. If errors are not provided, verification runs automatically first. Use this after verify_machine returns errors.',
95
+ description: 'Fix verify_machine errors using LLM. Loops until valid or max_iterations (default: 3). Pass errors array from verify_machine output, or omit to auto-verify first.',
96
96
  inputSchema: {
97
97
  type: 'object',
98
98
  properties: {
@@ -114,7 +114,7 @@ export const ORCA_TOOLS = [
114
114
  },
115
115
  {
116
116
  name: 'server_status',
117
- description: 'Return the MCP server version and active configuration. API keys are never included in the response — only whether a key is configured. Use this to confirm the server is running and check which LLM provider and model are active.',
117
+ description: 'Return MCP server version, active LLM provider/model, and configuration. API keys are never exposed — only whether a key is configured.',
118
118
  inputSchema: {
119
119
  type: 'object',
120
120
  properties: {},
package/dist/tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@orcalang/orca-lang",
3
- "version": "0.1.13",
3
+ "version": "0.1.16",
4
4
  "description": "Orca (Orchestrated State Machine Language) - an LLM-native code generation target",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/src/tools.ts CHANGED
@@ -16,7 +16,7 @@ export const ORCA_TOOLS: ToolDef[] = [
16
16
  {
17
17
  name: 'parse_machine',
18
18
  description:
19
- 'Parse an Orca machine definition and return its structure as JSON (states, events, transitions, guards, actions, context). Supports single and multi-machine files. Source must use "# machine Name" heading, "## state Name [initial]" for states, and a "## transitions" section with a | Source | Event | Guard | Target | Action | table.',
19
+ 'Parse .orca.md source → JSON (states, events, transitions, guards, actions, context). Syntax: # machine Name, ## state Name [initial|final], ## transitions table (| Source | Event | Guard | Target | Action |).',
20
20
  inputSchema: {
21
21
  type: 'object',
22
22
  properties: {
@@ -28,7 +28,7 @@ export const ORCA_TOOLS: ToolDef[] = [
28
28
  {
29
29
  name: 'verify_machine',
30
30
  description:
31
- 'Verify an Orca machine definition for structural correctness, completeness, and determinism. Checks that exactly one [initial] state exists, all states are reachable, no deadlocks exist (every non-final state handles all events or has timeouts), and guards on competing transitions are mutually exclusive. Returns structured errors and warnings.',
31
+ 'Verify machine structure: checks [initial] presence (exactly one), reachability, no deadlocks, guard determinism. Returns structured errors with codes and suggestions. Run before compile_machine.',
32
32
  inputSchema: {
33
33
  type: 'object',
34
34
  properties: {
@@ -40,7 +40,7 @@ export const ORCA_TOOLS: ToolDef[] = [
40
40
  {
41
41
  name: 'compile_machine',
42
42
  description:
43
- 'Compile a verified Orca machine to XState v5 config (TypeScript) or Mermaid stateDiagram-v2. Run verify_machine first to catch errors before compiling.',
43
+ 'Compile verified machine to XState v5 TypeScript or Mermaid stateDiagram-v2. Run verify_machine first. target: "xstate" (default) or "mermaid".',
44
44
  inputSchema: {
45
45
  type: 'object',
46
46
  properties: {
@@ -57,7 +57,7 @@ export const ORCA_TOOLS: ToolDef[] = [
57
57
  {
58
58
  name: 'generate_machine',
59
59
  description:
60
- 'Generate a draft Orca machine definition from a natural language specification. Automatically chooses between a single-machine or multi-machine design based on the spec: specs that mention a coordinator, orchestrator, or multiple independently-lifecycled sub-processes route to multi-machine; everything else produces a single machine. Returns raw .orca.md source and an is_multi flag. Always call verify_machine on the result next — then refine_machine if there are errors. Requires LLM configuration via environment variables (ANTHROPIC_API_KEY, etc.).',
60
+ 'Generate draft .orca.md from natural language spec. Returns source + is_multi flag. Always verify_machine next, then refine_machine if errors. Requires LLM API key (ANTHROPIC_API_KEY, etc.).',
61
61
  inputSchema: {
62
62
  type: 'object',
63
63
  properties: {
@@ -72,7 +72,7 @@ export const ORCA_TOOLS: ToolDef[] = [
72
72
  {
73
73
  name: 'generate_actions',
74
74
  description:
75
- 'Generate action scaffold code for an Orca machine in TypeScript, Python, or Go. Includes registration comments and optional test scaffolds. Requires a successfully parsed machine — pass verified .orca.md source.',
75
+ 'Generate action scaffold code from verified machine. lang: typescript (default), python, or go. Pass verified .orca.md source. use_llm: true for implementations vs templates. generate_tests: true for test scaffolds.',
76
76
  inputSchema: {
77
77
  type: 'object',
78
78
  properties: {
@@ -97,7 +97,7 @@ export const ORCA_TOOLS: ToolDef[] = [
97
97
  {
98
98
  name: 'generate_multi_machine',
99
99
  description:
100
- 'Generate a draft set of coordinated Orca machines from a natural language specification. Returns multiple machine definitions in one .orca.md file (separated by ---). Always call verify_machine on the result next — then refine_machine if there are errors. Requires LLM configuration via environment variables.',
100
+ 'Generate coordinated multi-machine .orca.md from spec (machines separated by ---). Use invoke: ChildMachine in states. Always verify_machine next, then refine_machine if errors. Requires LLM API key.',
101
101
  inputSchema: {
102
102
  type: 'object',
103
103
  properties: {
@@ -112,7 +112,7 @@ export const ORCA_TOOLS: ToolDef[] = [
112
112
  {
113
113
  name: 'refine_machine',
114
114
  description:
115
- 'Fix verification errors in an Orca machine using an LLM. Loops until the machine is valid or max_iterations is reached. If errors are not provided, verification runs automatically first. Use this after verify_machine returns errors.',
115
+ 'Fix verify_machine errors using LLM. Loops until valid or max_iterations (default: 3). Pass errors array from verify_machine output, or omit to auto-verify first.',
116
116
  inputSchema: {
117
117
  type: 'object',
118
118
  properties: {
@@ -136,7 +136,7 @@ export const ORCA_TOOLS: ToolDef[] = [
136
136
  {
137
137
  name: 'server_status',
138
138
  description:
139
- 'Return the MCP server version and active configuration. API keys are never included in the response — only whether a key is configured. Use this to confirm the server is running and check which LLM provider and model are active.',
139
+ 'Return MCP server version, active LLM provider/model, and configuration. API keys are never exposed — only whether a key is configured.',
140
140
  inputSchema: {
141
141
  type: 'object',
142
142
  properties: {},