@exellix/ai-tasks 9.1.0 → 9.1.1

package/.docs/blockers-and-issues.md

@@ -1,346 +0,0 @@
-# Blockers and Issues for @woroces/ai-tasks Package Setup
-
-**Date**: 2026-01-06  
-**Status**: Blocked on dependency installation  
-**Package**: `@woroces/ai-tasks`
-
-## Executive Summary
-
-The package setup is blocked because the primary dependency `@woroces/ai-skills` cannot be installed. Multiple issues are preventing successful dependency resolution and installation.
-
----
-
-## Primary Blocker: Missing Dependency Package
-
-### Issue #1: `@woroces/ai-skills` Not Found in GitHub Packages
-
-**Error Message**:
-```
-npm error 404 Not Found - GET https://npm.pkg.github.com/@woroces%2fai-skills
-npm error 404  '@woroces/ai-skills@*' is not in this registry.
-```
-
-**Root Cause**:
-- The package `@woroces/ai-skills` does not exist in the GitHub Packages registry under the `@woroces` organization
-- Attempts to install it result in 404 errors from both GitHub Packages and npmjs.org
-
-**Evidence**:
-1. `npm view @woroces/ai-skills --registry=https://npm.pkg.github.com` returns 404
-2. `npm search @woroces --registry=https://npm.pkg.github.com` returns 404
-3. The package is referenced in documentation (`.docs/building-runTask-sdk.md`, `.docs/building-skill-execution-orchestrator.md`) but doesn't exist in the registry
-
-**Possible Solutions**:
-1. **Publish the package first**: The `@woroces/ai-skills` package needs to be published to GitHub Packages before this package can depend on it
-2. **Use Git URL**: Install directly from GitHub repository (attempted but failed - see Issue #2)
-3. **Verify package name**: Confirm the actual package name (could be `@woroces/ai-skills` with different spelling, or under different organization)
-4. **Use local path**: If the package exists locally, use `file:` protocol in package.json
-
----
-
-## Issue #2: Registry Configuration Problems
-
-### npm Registry Resolution Order
-
-**Problem**:
-npm is attempting to fetch `@woroces/ai-skills` from `https://registry.npmjs.org` (public npm registry) instead of `https://npm.pkg.github.com` (GitHub Packages).
-
-**Error Pattern**:
-```
-npm error 404 Not Found - GET https://registry.npmjs.org/@woroces%2fai-skills
-```
-
-**Root Cause Analysis**:
-1. **Scope Configuration**: The `.npmrc` file correctly defines:
-   ```
-   @woroces:registry=https://npm.pkg.github.com
-   ```
-   However, npm might be:
-   - Checking the public registry first
-   - Not properly applying scope-based registry resolution
-   - Having cache issues
-
-2. **Token Authentication**: The token in `.npmrc` is valid (confirmed by `npm whoami` returning `ami-nx`), but npm might not be using it for the correct registry
-
-**Current `.npmrc` Configuration**:
-```
-@athenices:registry=https://npm.pkg.github.com
-@xronoces:registry=https://npm.pkg.github.com
-@xeonoces:registry=https://npm.pkg.github.com
-@woroces:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=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
-```
-
-**Issues Identified**:
-- ✅ **Spelling is consistent**: All files correctly use `@woroces` (with 'o')
-- ✅ `.npmrc` correctly defines `@woroces:registry=https://npm.pkg.github.com`
-- ✅ `package.json` correctly uses `@woroces/ai-skills`
-- ✅ Source code correctly imports from `@woroces/ai-skills`
-
-**No spelling mismatch found** - all references are consistent.
-
----
-
-## Issue #3: Git Installation Attempts Failed
-
-### Attempted Solution: Install from Git Repository
-
-**Command Attempted**:
-```bash
-npm install @woroces/ai-skills@git+ssh://git@github.com:woroces/ai-skills.git
-```
-
-**Result**: Failed with various errors:
-- Authentication issues
-- Repository access problems
-- Dependency resolution failures
-
-**Why It Failed**:
-1. The repository might not exist at `git@github.com:woroces/ai-skills.git`
-2. SSH key authentication might not be configured
-3. The repository might be private and require different authentication
-4. The package might not have a valid `package.json` in the repository root
-
----
-
-## Issue #4: TypeScript Types Installation
-
-### `@types/node` Version Resolution
-
-**Error**:
-```
-npm error code ETARGET
-npm error notarget No matching version found for @types/node@^20.0.0.
-```
-
-**Root Cause**:
-- The version `^20.0.0` might not exist in the registry being queried
-- npm might be looking in the wrong registry for this public package
-
-**Workaround Applied**:
-Changed to `"@types/node": "^18.0.0 || ^20.0.0"` to allow more flexibility
-
-**Status**: Partially resolved, but installation still fails due to primary blocker
-
----
-
-## Issue #5: Peer Dependency Warnings
-
-### AWS SDK Version Conflicts
-
-**Warnings Observed**:
-```
-npm warn ERESOLVE overriding peer dependency
-npm warn While resolving: @xronoces/xronox-storage-s3@2.0.1
-npm warn Found: @aws-sdk/client-s3@undefined
-npm warn Could not resolve dependency:
-npm warn peer @aws-sdk/client-s3@"^3.450.0" from @xronoces/xronox-storage-s3@2.0.1
-```
-
-**Impact**: 
-- These are warnings, not blockers
-- However, they indicate potential runtime issues if dependencies are resolved incorrectly
-- The `@aws-sdk/client-s3@undefined` suggests incomplete dependency resolution
-
----
-
-## Dependency Chain Analysis
-
-### Required Dependencies
-
-1. **Primary Dependency**: `@woroces/ai-skills`
-   - Status: ❌ NOT FOUND
-   - Required by: `src/task-sdk.ts` (imports `XeonoxSkillsClient`, `RunTaskRequest`, etc.)
-   - Impact: **BLOCKER** - Cannot build or test without this
-
-2. **Secondary Dependency**: `@athenices/execution-memory-manager`
-   - Status: ❓ UNKNOWN (not tested due to primary blocker)
-   - Required by: Type definitions for `JobHistory`, `TaskHistory`
-   - Impact: Medium - Types might be available from `@woroces/ai-skills` if it's installed
-
-3. **Peer Dependency**: `@athenices/ai-gateway`
-   - Status: ❓ UNKNOWN
-   - Required by: Underlying gateway functionality
-   - Impact: Low - Peer dependency, might be optional
-
-4. **Dev Dependencies**: `typescript`, `ts-node`, `@types/node`, `dotenv`
-   - Status: ⚠️ PARTIAL (some installed, some failed)
-   - Impact: Low - Can work around with manual installation
-
----
-
-## Authentication Status
-
-### GitHub Token Validation
-
-**Test Command**:
-```bash
-npm whoami --registry=https://npm.pkg.github.com
-```
-
-**Result**: ✅ **SUCCESS** - Returns `ami-nx`
-
-**Conclusion**: 
-- Token is valid and authenticated
-- Authentication is NOT the blocker
-- The issue is package availability, not access
-
----
-
-## Registry Resolution Flow
-
-### How npm Resolves Packages
-
-1. **Scoped Packages** (`@scope/package`):
-   - npm checks `.npmrc` for `@scope:registry=URL`
-   - If found, uses that registry
-   - If not found, falls back to default registry (npmjs.org)
-
-2. **Current Behavior**:
-   - npm finds `@woroces:registry` in `.npmrc` ✅
-   - Attempts to fetch from GitHub Packages ✅
-   - Package doesn't exist → 404 ❌
-   - Falls back to npmjs.org → 404 ❌
-   - Installation fails ❌
-
-3. **Scope Configuration**:
-   - ✅ `.npmrc` correctly has `@woroces:registry=https://npm.pkg.github.com`
-   - ✅ `package.json` correctly uses `@woroces/ai-skills`
-   - ✅ All references are consistent with `@woroces` (with 'o')
-   - **No spelling issues found**
-
----
-
-## Recommended Actions
-
-### Immediate Fixes
-
-1. **Verify Package Existence**:
-   - Check if `@woroces/ai-skills` exists in GitHub Packages
-   - Confirm the package has been published (current version `^3.3.6` per package.json)
-   - Verify the package is accessible with the current token
-
-3. **Alternative: Use Git URL** (if repository exists):
-   ```json
-   {
-     "dependencies": {
-       "@woroces/ai-skills": "git+ssh://git@github.com:woroces/ai-skills.git"
-     }
-   }
-   ```
-
-4. **Alternative: Use Local Path** (if package exists locally):
-   ```json
-   {
-     "dependencies": {
-       "@woroces/ai-skills": "file:../ai-skills"
-     }
-   }
-   ```
-
-### Long-term Solutions
-
-1. **Publish `@woroces/ai-skills` to GitHub Packages**:
-   - This is the proper solution
-   - Ensures version management
-   - Enables proper dependency resolution
-
-2. **Organization Naming**:
-   - ✅ All references consistently use `@woroces` (with 'o')
-   - ✅ No standardization needed - already consistent
-
-3. **Create Package Registry Documentation**:
-   - Document which packages exist where
-   - Create a registry map
-   - Include installation instructions
-
----
-
-## Testing Status
-
-### What We CAN Test
-
-- ✅ TypeScript compilation (if dev dependencies install)
-- ✅ Package structure
-- ✅ Code syntax and types
-
-### What We CANNOT Test
-
-- ❌ Actual `runTask` functionality (requires `@woroces/ai-skills`)
-- ❌ Integration with AI Gateway
-- ❌ Real skill execution
-- ❌ Memory management features
-- ❌ Context enrichment
-
-### Workaround for Testing
-
-1. **Mock Implementation**:
-   - Create mock `XeonoxSkillsClient`
-   - Test SDK structure without real dependencies
-   - Validate API surface
-
-2. **Integration Test Later**:
-   - Once `@woroces/ai-skills` is available
-   - Run full integration tests
-   - Test with real credentials from `.env`
-
----
-
-## Environment Variables Status
-
-### Credentials Available
-
-The user mentioned having valid credentials in `.env`:
-- ✅ GitHub token (validated via `npm whoami`)
-- ✅ AI provider keys (assumed available)
-- ✅ Content registry URL (assumed available)
-
-**Impact**: 
-- Once dependencies are resolved, the package should work
-- ERC (Env-Ready) compliance can be tested
-- Real integration tests can be run
-
----
-
-## Summary
-
-### Narrix / subnet playground (unblocked)
-
-The narrix run path and subnet batch playground (`npm run local:narrix:subnets`) are unblocked: narrix deps resolve, pack registry includes subnetEgress, and ai-tasks uses `defaultIngest` and normalizes array-shaped test-data to a single record per file. See [GAP-AND-BUGS-RESOLVED.md](../GAP-AND-BUGS-RESOLVED.md) for what was fixed.
-
-### Critical Blockers
-
-1. **PRIMARY**: `@woroces/ai-skills` package (version `^3.3.6`) cannot be installed from GitHub Packages
-2. **SECONDARY**: Git installation attempts failing (repository might not exist or inaccessible)
-3. **TERTIARY**: npm registry resolution may be checking wrong registry first
-
-### Resolution Path
-
-1. Fix `.npmrc` scope spelling
-2. Verify/obtain `@woroces/ai-skills` package
-3. Install dependencies
-4. Build package
-5. Run real tests with `.env` credentials
-
-### Current State
-
-- ✅ Package structure created
-- ✅ Code written and typed correctly
-- ✅ Documentation complete
-- ❌ Dependencies cannot be installed
-- ❌ Cannot build or test
-- ⚠️ Blocked until `@woroces/ai-skills` is available
-
----
-
-## Next Steps
-
-1. **Immediate**: Verify `@woroces/ai-skills@^3.3.6` exists in GitHub Packages and is accessible
-2. **Verify**: Check if the repository `git@github.com:woroces/ai-skills.git` exists and is accessible
-3. **Test Authentication**: Confirm token has proper permissions for the package
-4. **Alternative**: Use local development setup if package exists locally
-5. **Test**: Once dependencies resolve, run full integration tests
-
----
-
-**Last Updated**: 2026-01-06  
-**Next Review**: After `@woroces/ai-skills` availability is confirmed