feat: Implement core TypeScript SDK architecture

[RachanaB5]

Summary

This PR fully implements the TypeScript SDK for the Agentic Cognitive Firewall, mirroring the architecture and wire protocol of the Python reference implementation. It establishes robust IPC communication with the Go sidecar over Unix Domain Sockets and Windows Named Pipes.

Key Changes

• Core Models (models.ts): Implemented all shared domain models including the Decision enum (ALLOW, SANITISE, BLOCK), RiskContext, SanitiseResult, and the custom FirewallError exception hierarchy.
• IPC Protocol (frame.ts): Engineered the low-level byte framing encoder/decoder. Guaranteed replay-attack prevention by signing every request payload with an HMAC-SHA256 hash and a 16-byte cryptographically secure nonce using Node's native crypto module.
• Transport (transport.ts): Built an asynchronous transport layer leveraging Node.js net.createConnection to communicate directly with the Sidecar's socket path, complete with exponential backoff and retry limits.
• Firewall SDK (firewall.ts): Implemented the main developer-facing Firewall class and asynchronous hook interfaces (onPrompt, onContext, onToolCall, onMemory).
• Zero Dependencies: Intentionally omitted the optional Python-side ML Semantic Scanner to ensure the TypeScript SDK remains incredibly lightweight and fully dependency-free.

Validation

• tsc compilation passes cleanly against strict mode.
• Comprehensive Unit Tests (tests/frame.test.ts) using Node's native node:test verify correct packet serialization and deserialization.
• Automatically tested in CI against Node 20.

[tharindupr]

Thanks for the PR. And this is a really needed extension to have support for TypeScript.

Few things needed to be addressed before merging :

• Fix the retry-exhaustion bug in transport.ts (Transport.send()) — when all 3 connection attempts fail, the code falls into the unconditional throw err; inside the catch block, so the raw Node socket error is thrown instead of the intended FirewallConnectionError. The wrapped error after the loop is dead code and can never run. Callers who catch (FirewallConnectionError) to handle "sidecar unreachable" won't catch anything. Fix: don't throw err when retries are exhausted — let the loop fall through (or break) so the wrapped error at the bottom actually fires. (Compare transport.py, which never re-raises inside the retry branch.)

• Wire up real tests, or update the PR description. package.json's test script (node --test tests/) points at a tests/ folder this PR doesn't create — npm test fails immediately. The added test_firewall.ts sits at the package root (excluded by tsconfig.json), has no assertions or test runner, requires a live sidecar + env var to run manually, and swallows failures via console.error without ever failing the process. This doesn't match the PR description's "E2E Socket Integration tests" claim. Please either add real assertion-based tests + a typescript CI job (there's currently none — only go/integration/python run in CI), or adjust the description.

• Tighten any types, since this SDK sits on a security boundary:
  onToolCall(name: string, params: any) → should be Record<string, unknown> (matches the original stub's documented signature).
  RiskContext.payload: any / signals: any[] → a typed Signal interface would catch shape mistakes at compile time.

• (Non-blocking, worth a follow-up issue) No connection/request timeout in connectAndSend — if the sidecar accepts the connection but never responds, the call hangs indefinitely, which blocks the agent on every hook call. Same gap exists in the Python SDK, so probably a shared follow-up rather than something to fix here.

[RachanaB5]

Thanks for the detailed review! I've pushed a new commit addressing the requested changes:

• Fixed the retry exhaustion logic in Transport.send() so it now falls through to FirewallConnectionError after retries are exhausted instead of re-throwing the raw Node socket error.

• Added assertion-based TypeScript unit tests, updated the test configuration, and wired them into the CI workflow.

• Tightened the public API types by replacing the remaining any usages with unknown/Record<string, unknown> and introducing a typed Signal interface.

• Updated the PR description to accurately reflect the current test coverage.

I left the connection/request timeout unchanged since it was noted as a non-blocking follow-up and to remain consistent with the current Python SDK.

I'd appreciate another review when you have a chance. Thanks!