@irogane/kaji 0.2.0-beta.11

package/contracts/cli/init-cases-v1.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schemaVersion": 1,
+  "grammar": "kaji [--no-color] [--verbose] init [path] --provider mock|openai|anthropic --yes --force",
+  "defaults": {
+    "path": ".",
+    "provider": "mock"
+  },
+  "exitCodes": {
+    "successOrHelp": 0,
+    "validationRuntimeOrConflict": 1,
+    "usage": 2
+  },
+  "cases": [
+    { "name": "defaults", "args": [], "exitCode": 0 },
+    { "name": "explicit-path", "args": ["project"], "exitCode": 0 },
+    { "name": "mock-provider", "args": ["--provider", "mock"], "exitCode": 0 },
+    { "name": "openai-provider", "args": ["--provider", "openai"], "exitCode": 0 },
+    { "name": "anthropic-provider", "args": ["--provider", "anthropic"], "exitCode": 0 },
+    { "name": "yes", "args": ["--yes"], "exitCode": 0 },
+    { "name": "force", "args": ["--force"], "setup": "existing-file", "exitCode": 0 },
+    { "name": "unknown-provider", "args": ["--provider", "unknown"], "exitCode": 2 },
+    { "name": "missing-provider-value", "args": ["--provider"], "exitCode": 2 },
+    { "name": "unknown-option", "args": ["--unknown"], "exitCode": 2 },
+    { "name": "existing-file-refusal", "args": [], "setup": "existing-file", "exitCode": 1 }
+  ]
+}

package/contracts/errors/error-codes.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/contracts/errors/error-codes.json",
+  "version": "1.0.0",
+  "codes": [
+    "INVALID_TOOL_SCHEMA",
+    "INVALID_TOOL_ARGUMENTS",
+    "INVALID_DURABLE_VALUE",
+    "INVALID_TOOL_RESULT",
+    "UNCLASSIFIED_TOOL_RISK",
+    "MISSING_TOOL_IDENTITY",
+    "TOOL_NOT_ALLOWED",
+    "APPROVAL_UNAVAILABLE",
+    "APPROVAL_REJECTED",
+    "APPROVAL_TIMEOUT",
+    "TOOL_CANCELLED",
+    "TOOL_TIMEOUT",
+    "TOOL_EXECUTION_FAILED",
+    "TOOL_START_RECORD_FAILED",
+    "EVENT_APPEND_FAILED",
+    "EVENT_PUBLISH_FAILED",
+    "EVENT_ID_CONFLICT",
+    "EVENT_BUFFER_OVERFLOW",
+    "EVENT_PAYLOAD_TOO_LARGE",
+    "EVENT_SCHEMA_INCOMPATIBLE",
+    "EVENT_STORE_CAPACITY_EXCEEDED",
+    "IDEMPOTENCY_CAPACITY_EXCEEDED",
+    "IDEMPOTENCY_CONFLICT",
+    "PROVIDER_API_ERROR",
+    "PROVIDER_AUTH_ERROR",
+    "PROVIDER_CONFIG_ERROR",
+    "PROVIDER_NETWORK_ERROR",
+    "PROVIDER_RATE_LIMITED",
+    "PROVIDER_OUTPUT_LIMIT",
+    "PROVIDER_CANCELLATION_CONTRACT_VIOLATION",
+    "TURN_TIMEOUT",
+    "INTEGRATION_SCHEMA_INVALID",
+    "INTEGRATION_ABI_MISMATCH",
+    "INTEGRATION_EXPERIMENTAL",
+    "INTEGRATION_API_ERROR",
+    "INTEGRATION_AUTH_REQUIRED",
+    "INTEGRATION_AUTH_ERROR",
+    "INTEGRATION_RATE_LIMITED",
+    "INTEGRATION_POLICY_REJECTED",
+    "INTEGRATION_REDIRECT_REJECTED",
+    "INTEGRATION_RESPONSE_LIMIT"
+  ]
+}

package/contracts/errors/integration-recovery-v1.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/contracts/errors/integration-recovery-v1.json",
+  "version": "1.0.0",
+  "entries": {
+    "github_token_missing": {
+      "errorCode": "INTEGRATION_AUTH_REQUIRED",
+      "recoveryCode": "CONFIGURE_GITHUB_TOKEN",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#github-token",
+      "problem": "GitHub authentication is required.",
+      "cause": "The configured GitHub token is unavailable.",
+      "fix": "Set the manifest-declared GitHub token environment variable and retry."
+    },
+    "gmail_grant_missing": {
+      "errorCode": "INTEGRATION_AUTH_REQUIRED",
+      "recoveryCode": "CONNECT_GMAIL",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#gmail-grant",
+      "problem": "Gmail authorization is required.",
+      "cause": "No Gmail grant exists for this principal.",
+      "fix": "Use the package-qualified connect command for this runtime and principal, then retry."
+    },
+    "keychain_missing": {
+      "errorCode": "INTEGRATION_AUTH_ERROR",
+      "recoveryCode": "RESTORE_KEYCHAIN",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#keychain-missing",
+      "problem": "The macOS Keychain is unavailable.",
+      "cause": "The Keychain command could not be found.",
+      "fix": "Restore `/usr/bin/security` on a supported macOS host and retry."
+    },
+    "keychain_locked": {
+      "errorCode": "INTEGRATION_AUTH_ERROR",
+      "recoveryCode": "UNLOCK_KEYCHAIN",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#keychain-locked",
+      "problem": "The macOS Keychain is locked.",
+      "cause": "The stored integration grant cannot be read while Keychain is locked.",
+      "fix": "Unlock the login Keychain and retry."
+    },
+    "keychain_corrupt": {
+      "errorCode": "INTEGRATION_AUTH_ERROR",
+      "recoveryCode": "RESET_GMAIL_GRANT",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#keychain-corrupt",
+      "problem": "The stored Gmail grant is invalid.",
+      "cause": "The Keychain entry is corrupt or incomplete.",
+      "fix": "Disconnect Gmail locally, then reconnect with the same principal."
+    },
+    "keychain_unsupported": {
+      "errorCode": "INTEGRATION_AUTH_ERROR",
+      "recoveryCode": "USE_SUPPORTED_KEYCHAIN",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#keychain-unsupported",
+      "problem": "Secure Gmail grant storage is unsupported.",
+      "cause": "This host cannot provide the required macOS Keychain boundary.",
+      "fix": "Use a supported macOS host; do not fall back to plaintext storage."
+    },
+    "gmail_scope_drift": {
+      "errorCode": "INTEGRATION_AUTH_REQUIRED",
+      "recoveryCode": "RECONNECT_GMAIL",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#gmail-scope-drift",
+      "problem": "The Gmail grant no longer has the required scopes.",
+      "cause": "Stored and required OAuth scopes differ.",
+      "fix": "Use the package-qualified connect command for this runtime and principal, then consent again."
+    },
+    "policy_rejected": {
+      "errorCode": "INTEGRATION_POLICY_REJECTED",
+      "recoveryCode": "REVIEW_INTEGRATION_POLICY",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#policy-rejected",
+      "problem": "The integration request was rejected before dispatch.",
+      "cause": "A fixed-origin, repository, recipient, or schema policy did not match.",
+      "fix": "Review the integration allowlist and request shape before retrying."
+    },
+    "api_rejected": {
+      "errorCode": "INTEGRATION_API_ERROR",
+      "recoveryCode": "REVIEW_PROVIDER_REJECTION",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#api-rejected",
+      "problem": "The provider rejected the integration request.",
+      "cause": "The provider returned a confirmed non-retryable API rejection.",
+      "fix": "Review the request against the provider response guidance before retrying manually."
+    },
+    "transient_read_failed": {
+      "errorCode": "INTEGRATION_API_ERROR",
+      "recoveryCode": "RETRY_INTEGRATION_READ",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#transient-read",
+      "problem": "The integration read did not complete.",
+      "cause": "The provider returned a transient failure before any external effect.",
+      "fix": "Retry the idempotent read with bounded backoff."
+    },
+    "rate_limited": {
+      "errorCode": "INTEGRATION_RATE_LIMITED",
+      "recoveryCode": "RETRY_AFTER_RATE_LIMIT",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#rate-limited",
+      "problem": "The provider rate limit was reached.",
+      "cause": "The provider confirmed that this request was rate limited.",
+      "fix": "Reduce parallelism and retry only after the bounded provider delay."
+    },
+    "redirect_rejected": {
+      "errorCode": "INTEGRATION_REDIRECT_REJECTED",
+      "recoveryCode": "REJECT_PROVIDER_REDIRECT",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#redirect-rejected",
+      "problem": "The provider returned a redirect that Kaji will not follow.",
+      "cause": "Fixed-origin integration requests reject every redirect.",
+      "fix": "Verify the provider endpoint; do not retry an ambiguous mutation blindly."
+    },
+    "response_limit_exceeded": {
+      "errorCode": "INTEGRATION_RESPONSE_LIMIT",
+      "recoveryCode": "REDUCE_INTEGRATION_RESPONSE",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#response-limit",
+      "problem": "The integration response exceeded a safety bound.",
+      "cause": "Provider headers or body were malformed or too large.",
+      "fix": "Narrow the read request; reconcile a mutation before any retry."
+    },
+    "github_mutation_unknown": {
+      "errorCode": "TOOL_EXECUTION_FAILED",
+      "recoveryCode": "RECONCILE_GITHUB_MUTATION",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#github-mutation-unknown",
+      "problem": "The GitHub mutation outcome is unknown.",
+      "cause": "The connection failed after dispatch without a confirmed provider result.",
+      "fix": "Reconcile the GitHub issue or comment marker before any manual retry."
+    },
+    "gmail_mutation_unknown": {
+      "errorCode": "TOOL_EXECUTION_FAILED",
+      "recoveryCode": "RECONCILE_GMAIL_MUTATION",
+      "docUrl": "https://kaji.dev/docs/integrations/recovery-v1#gmail-mutation-unknown",
+      "problem": "The Gmail mutation outcome is unknown.",
+      "cause": "The connection failed after dispatch without a confirmed provider result.",
+      "fix": "Reconcile the Gmail draft key or sent message before any manual retry."
+    }
+  }
+}

package/contracts/errors/provider-normalization.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/contracts/errors/provider-normalization.json",
+  "version": "1.0.0",
+  "cases": [
+    {
+      "name": "config",
+      "source": "config",
+      "status": null,
+      "expected": {
+        "type": "config",
+        "code": "PROVIDER_CONFIG_ERROR",
+        "service": "fixture",
+        "action": "configure",
+        "status": null,
+        "retryable": false
+      }
+    },
+    {
+      "name": "network",
+      "source": "network",
+      "status": null,
+      "expected": {
+        "type": "network",
+        "code": "PROVIDER_NETWORK_ERROR",
+        "service": "fixture",
+        "action": "stream",
+        "status": null,
+        "retryable": true
+      }
+    },
+    {
+      "name": "api-without-status",
+      "source": "api",
+      "status": null,
+      "expected": {
+        "type": "api",
+        "code": "PROVIDER_API_ERROR",
+        "service": "fixture",
+        "action": "request",
+        "status": null,
+        "retryable": false
+      }
+    },
+    {
+      "name": "api-400",
+      "source": "api",
+      "status": 400,
+      "expected": {
+        "type": "api",
+        "code": "PROVIDER_API_ERROR",
+        "service": "fixture",
+        "action": "request",
+        "status": 400,
+        "retryable": false
+      }
+    },
+    {
+      "name": "api-401-is-auth",
+      "source": "api",
+      "status": 401,
+      "expected": {
+        "type": "auth",
+        "code": "PROVIDER_AUTH_ERROR",
+        "service": "fixture",
+        "action": "request",
+        "status": 401,
+        "retryable": false
+      }
+    },
+    {
+      "name": "api-403-is-auth",
+      "source": "api",
+      "status": 403,
+      "expected": {
+        "type": "auth",
+        "code": "PROVIDER_AUTH_ERROR",
+        "service": "fixture",
+        "action": "request",
+        "status": 403,
+        "retryable": false
+      }
+    },
+    {
+      "name": "api-429-is-rate-limited",
+      "source": "api",
+      "status": 429,
+      "expected": {
+        "type": "rate_limit",
+        "code": "PROVIDER_RATE_LIMITED",
+        "service": "fixture",
+        "action": "request",
+        "status": 429,
+        "retryable": true
+      }
+    },
+    {
+      "name": "api-500-is-retryable",
+      "source": "api",
+      "status": 500,
+      "expected": {
+        "type": "api",
+        "code": "PROVIDER_API_ERROR",
+        "service": "fixture",
+        "action": "request",
+        "status": 500,
+        "retryable": true
+      }
+    }
+  ]
+}

package/contracts/events/conformance-invalid.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "cases": [
+    { "name": "missing-event-id", "kind": "new", "event": { "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s" }, "path": "/id" },
+    { "name": "missing-version", "kind": "new", "event": { "id": "e", "type": "session.created", "timestamp": 0, "session_id": "s" }, "path": "/version" },
+    { "name": "missing-timestamp", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "session_id": "s" }, "path": "/timestamp" },
+    { "name": "missing-session-id", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0 }, "path": "/session_id" },
+    { "name": "missing-event-type", "kind": "new", "event": { "id": "e", "version": "1.0", "timestamp": 0, "session_id": "s" }, "path": "/type" },
+    { "name": "empty-event-id", "kind": "new", "event": { "id": "", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s" }, "path": "/id" },
+    { "name": "empty-session-id", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "" }, "path": "/session_id" },
+    { "name": "empty-present-turn-id", "kind": "new", "event": { "id": "e", "type": "agent.reasoning.started", "version": "1.0", "timestamp": 0, "session_id": "s", "turn_id": "" }, "path": "/turn_id" },
+    { "name": "unknown-event-type", "kind": "new", "event": { "id": "e", "type": "unknown", "version": "1.0", "timestamp": 0, "session_id": "s" }, "path": "/type" },
+    { "name": "extra-field", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s", "extra": true }, "path": "/extra" },
+    { "name": "draft-has-sequence", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s", "sequence": 1 }, "path": "/sequence" },
+    { "name": "stored-missing-sequence", "kind": "stored", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s" }, "path": "/sequence" },
+    { "name": "unsafe-integral-number", "kind": "new", "event": { "id": "e", "type": "session.created", "version": "1.0", "timestamp": 0, "session_id": "s", "metadata": { "n": 9007199254740992 } }, "path": "/metadata/n" },
+    { "name": "partial-integration-recovery", "kind": "new", "event": { "id": "e", "type": "tool.call.failed", "version": "1.0", "timestamp": 0, "session_id": "s", "turn_id": "t", "tool_name": "integration", "tool_call_id": "c", "error": "Tool execution failed", "reason_code": "policy_rejected" }, "path": "/reason_code" },
+    { "name": "mismatched-integration-recovery", "kind": "new", "event": { "id": "e", "type": "tool.call.failed", "version": "1.0", "timestamp": 0, "session_id": "s", "turn_id": "t", "tool_name": "integration", "tool_call_id": "c", "error": "Tool execution failed", "reason_code": "policy_rejected", "recovery_code": "CONNECT_GMAIL", "doc_url": "https://kaji.dev/docs/integrations/recovery-v1#policy-rejected" }, "path": "/reason_code" }
+  ]
+}