open-agreements 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-agreements",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "workspaces": [
     "packages/allure-test-factory",
     "packages/contract-templates-mcp",

package/skills/delaware-franchise-tax/SKILL.md

@@ -23,8 +23,8 @@ File your Delaware annual franchise tax and annual report.
 ## Security model
 
 - This skill **does not** download or execute any code.
-- It **does not** access the Delaware eCorp portal programmatically (the portal prohibits automated tools).
 - All portal interactions are performed by the user, guided step-by-step by the agent.
+- If the user opts in to browser automation (Playwright via CDP), the agent may assist with portal navigation — but credit card and banking details must **always** be entered by the user directly.
 
 ## When to Use
 
@@ -117,28 +117,64 @@ Total due:                     $XXX + $50 = $XXX
 
 ## Phase 3: File via Portal
 
-Guide the user step by step. The agent reads instructions aloud; the user operates the browser.
+The agent can automate the portal using Playwright if Chrome is running with remote debugging enabled. Otherwise, guide the user step-by-step.
+
+### Automation Setup (Playwright via CDP)
+
+If the user says "use playwright", "use the browser" or requests similar automation:
+
+1. **Launch Chrome with remote debugging** (see `reference/ecorp-portal-playwright-notes.md` for commands)
+2. **Connect via Playwright** (see reference for CDP connection snippet)
+3. **Portal field reference**: See `reference/ecorp-portal-playwright-notes.md` for:
+   - All field selector IDs
+   - Date field workaround (must use JS `el.value =` not Playwright `.fill()`)
+   - State dropdown abbreviations (use `value="NY"` not `label="New York"`)
+   - Director name fields (separate first/middle/last fields, NOT one name field)
+   - APVC activation sequence
+   - Session/eId behavior
+
+### Filing Steps
 
 1. **Navigate**: Open https://icis.corp.delaware.gov/ecorp/logintax.aspx
 2. **Login**: Enter Business Entity File Number. Solve CAPTCHA (if the user shares a screenshot, the agent can try to read it). Click **Continue**.
 3. **Entity verification**: Confirm entity name, registered agent, and registered office match your records.
-4. **Officers and directors**: Review and confirm or update names and addresses. Enter Nature of Business if prompted.
-5. **Stock information**: Enter authorized shares, par value, issued shares, and gross assets for each class.
-6. **Tax method**: Select **Assumed Par Value Capital Method** (or whichever method produced the lower tax). Verify the displayed tax matches your calculation from Phase 2. If it does not match, stop and troubleshoot before proceeding.
-7. **Payment**: Enter credit card or ACH details. Total = tax + filing fee. **Click Submit ONCE** — the portal warns about duplicate charges on double-click. If tax exceeds $5,000, ACH payment is required.
-8. **Confirmation**: Save the confirmation number. Screenshot the confirmation page.
-
-## Phase 4: Record and Remind
-
-Save a filing record with the following details:
-- Entity name
-- Delaware file number
-- Tax year
-- Calculation method used and intermediate values
-- Amount paid (tax + filing fee)
-- Confirmation number
-- Date filed
-- Next due date (March 1 of next year for corps, June 1 for LLCs)
+4. **Fill form fields** (all on one page):
+   - **Stock info**: Issued shares (per-class field, NOT the readonly total), gross assets, asset date (must == fiscal year end)
+   - **Address**: Principal business address with state abbreviation
+   - **Nature of business**: Select from dropdown (e.g., "Technology/Software")
+   - **Officer**: First/middle/last name, title, address
+   - **Directors**: Set total count, click "Enter Directors Info", fill first/middle/last name + address for each
+   - **Authorization**: First/middle/last name, title, address
+   - **T&C checkbox**: Must check `chkCertify` before continuing
+5. **Recalculate tax**: Click "Recalculate Tax" button. Verify the displayed tax matches your calculation from Phase 2. If it still shows the Authorized Shares method amount, the asset date is probably wrong — fix it via JavaScript.
+6. **Review**: Click "Continue Filing" to see the Review Copy. Verify all data.
+7. **Payment**: Click "Proceed to Payment". The agent **must stop here** — credit card and banking details must be entered by the user. If tax exceeds $5,000, ACH payment is required.
+8. **Confirmation**: After payment:
+   - Click **"Display Confirmation Copy"** (`onclick="downloadConfirmation();return false;"`) to save receipt PDF
+   - Click **"Email Confirmation Copy"** to email the filed report (opens popup at `Email.aspx`, enter email address)
+   - **CRITICAL**: "Once you leave this screen, you will no longer be able to obtain a confirmation copy" — save/email before navigating away
+   - Record the Service Request Number from the URL: `srNo=XXXXX`
+
+## Phase 4: Save Receipt and Remind
+
+### Save the confirmation PDF
+
+The downloaded confirmation PDF **is** the filing record — no need to create a separate one.
+
+The portal downloads the receipt as `Ecorp_Confirmation_<ServiceRequestNumber>.pdf` to the default Downloads folder. Move it to a durable location:
+- `~/Documents/Tax/Delaware/<EntityName>/` on local disk
+- A "Tax" or "Corporate Records" folder in cloud storage if available
+- Keep the original filename — it contains the Service Request Number for future reference
+
+```bash
+# Example
+mkdir -p ~/Documents/Tax/Delaware/My-Corp-Name
+mv ~/Downloads/Ecorp_Confirmation_*.pdf ~/Documents/Tax/Delaware/My-Corp-Name/
+```
+
+Ask the user where they keep tax records and move the file there.
+
+### Set a reminder
 
 Remind the user to set an annual reminder for approximately 2 weeks before the deadline:
 - **Mid-February** for corporations (March 1 deadline)
@@ -156,6 +192,7 @@ For detailed calculation formulas and official guidance, see the `reference/` di
 - `reference/tax-calculation.md` — full formulas for both methods with examples
 - `reference/filing-instructions.md` — fees, payment methods, deadlines
 - `reference/faq.md` — frequently asked questions
+- `reference/ecorp-portal-playwright-notes.md` — field selectors, gotchas, and automation tips for the eCorp portal
 
 **Official source**: https://corp.delaware.gov/paytaxes/
 **Help line**: 302-739-3073, Option 3

package/skills/delaware-franchise-tax/reference/ecorp-portal-playwright-notes.md

@@ -0,0 +1,136 @@
+# Delaware eCorp Portal — Playwright Automation Notes
+
+## Setup
+
+### Launch Chrome with remote debugging
+
+```bash
+# Must quit Chrome first, then relaunch with debug port
+osascript -e 'tell application "Google Chrome" to quit'
+sleep 2
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-debug-profile &
+```
+
+### Connect via Playwright (CDP)
+
+```python
+NODE_OPTIONS='--no-deprecation' uv run python3 << 'PYEOF'
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp("http://localhost:9222")
+    ctx = browser.contexts[0]
+    page = ctx.pages[0]
+PYEOF
+```
+
+## Fixes & Gotchas
+
+### 1. Readonly "Total Issued Shares" field
+- `gridStock_ctl02_txtIssuedShares` is **readonly** — it's auto-summed from per-class fields
+- Fill the per-class field instead: `gridStock_ctl02_gridStockDetails_ctl02_txtIssuedShares`
+- This populates the readonly total automatically on recalculate
+
+### 2. Asset Date field mangles input with Playwright .fill()/.type()
+- The date field has a mask/formatter that garbles Playwright keyboard input
+- **Fix**: Use JavaScript to set the value directly:
+  ```python
+  page.evaluate('''
+      const el = document.getElementById('ctl00_ContentPlaceHolder1_gridStock_ctl02_txtAssetDate');
+      el.value = '12/31/2025';
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+  ''')
+  ```
+- The portal requires asset date == fiscal year end date, or it ignores gross assets
+
+### 3. APVC method activation
+- Portal defaults to Authorized Shares method ($85,165 for 10M shares)
+- To get APVC: fill issued shares + gross assets + correct asset date, then click "Recalculate Tax"
+- If asset date doesn't match fiscal year end, recalculate silently stays on Authorized Shares
+
+### 4. ASP.NET ViewState breaks on back-navigation
+- Never use `page.go_back()` — the ViewState expires and you get a server error
+- Always start fresh from the login page: `https://icis.corp.delaware.gov/ecorp/logintax.aspx`
+
+### 5. Postback links (2024 "File Amended Annual Report")
+- The link is `javascript:__doPostBack(...)`, not a real URL
+- Can't open in a new tab via href — must execute on the page
+- Use: `page.evaluate("__doPostBack('ctl00$ContentPlaceHolder1$lnkPrevAR','')")`
+
+### 6. CAPTCHA
+- Field: `#ctl00_ContentPlaceHolder1_ecorpCaptcha1_txtCaptcha`
+- Image: `#ctl00_ContentPlaceHolder1_ecorpCaptcha1_captchaImage` (NOT `img[src*='Captcha']`)
+- Case-insensitive in practice (all caps in image)
+- Screenshot cropping can be unreliable — fetch the CAPTCHA image bytes via JS `fetch()` on `img.src` as fallback
+
+### 7. Key field selectors
+| Field | Selector ID (after ctl00_ContentPlaceHolder1_) |
+|-------|------------------------------------------------|
+| File number | txtPrimaryFileNo |
+| CAPTCHA | ecorpCaptcha1_txtCaptcha |
+| Continue button | btnContinue |
+| Issued shares (per-class) | gridStock_ctl02_gridStockDetails_ctl02_txtIssuedShares |
+| Issued shares (total, readonly) | gridStock_ctl02_txtIssuedShares |
+| Gross assets | gridStock_ctl02_txtGrossAsset |
+| Asset date | gridStock_ctl02_txtAssetDate |
+| Fiscal year end | txtFiscalYearEndYear |
+| Recalculate button | btnRecalucation (note: typo in portal) |
+| Continue Filing button | btnProceedPayment |
+| Enter Directors button | btnDisplayDirectorForm |
+| Nature of Business | ddlBusinessNatures |
+
+### 8. State dropdowns use abbreviations (NY, WA, etc.)
+- All state dropdowns (`drpHidePrincipal`, `drpHideOfficer`, `drpHideAuthor`, `drpDirectorStatesN`) use 2-letter state codes
+- Use `page.select_option("#drpHidePrincipal", value="NY")` — NOT `label="New York"`
+
+### 9. Director form fields (inline, not popup)
+- Click `#btnDisplayDirectorForm` to reveal director rows
+- **CRITICAL**: Director names have THREE separate fields per director:
+  - `txtDirectorName{N}` = **first name only** (NOT full name!)
+  - `txtMiddleName{N}` = middle name/initial
+  - `txtLastName{N}` = last name (REQUIRED — validation fails without it)
+- Other fields: `txtDirectorAddress{N}`, `txtDirectorCity{N}`, `drpDirectorStates{N}`, `txtDirectorZip{N}`, `drpDirectorCountry{N}`
+- Numbered 1–N based on `txtTotalNumOfDirectors`
+- All use simple IDs (no ASP.NET prefix)
+
+### 10. Tax result label IDs (different from what you'd expect)
+| Label | Selector ID (after ctl00_ContentPlaceHolder1_) |
+|-------|------------------------------------------------|
+| Franchise Tax | lblFranchisetaxData |
+| Penalty | lblPenaltyData |
+| Interest | lblMonthlyIntrestData |
+| Filing Fee | lblAnnualFilingDta |
+| Credit | lblPreviousData |
+| Prepaid | lblPrepaidPaymentData |
+| **Total Due** | **lblAmountDue** |
+
+### 11. Officer and Authorization address fields
+| Section | Street | City | State | Zip |
+|---------|--------|------|-------|-----|
+| Principal | txtStreetPrincipal | txtCityPrincipal | drpHidePrincipal | txtZipPrincipal |
+| Officer | txtStreetOfficer | txtCityOfficer | drpHideOfficer | txtZipOfficer |
+| Auth | txtStreetAuthorization | txtCityAuthorization | drpHideAuthor | txtZipAuthorization |
+
+### 12. Session/eId behavior
+- Dashboard URL needs `eId` parameter from login — can't bookmark dashboard directly
+- **BUT**: Cmd+Back (browser history) in a new tab CAN get back to dashboard within the same session
+- Each login generates a unique eId; session cookies are shared across tabs
+
+### 13. T&C checkbox required before Continue Filing
+- Must check `#ctl00_ContentPlaceHolder1_chkCertify` before clicking Continue Filing
+- Validation error: "Authorization: Please check the box to confirm that you have read the Terms and Conditions"
+
+### 14. Confirmation page — save BEFORE navigating away
+- **"Once you leave this screen, you will no longer be able to obtain a confirmation copy"**
+- **PDF download**: `downloadConfirmation()` → opens `DownLoadConfirmation.ashx?srNo=...&fileNo=...`
+  - Triggers a file download, NOT a page navigation — Playwright will throw "Download is starting" error (that's OK, the file downloads)
+- **Email confirmation**: `openARemail()` → opens `Email.aspx?srNo=...` popup
+  - Fill `#txtEmailAddress` and `#txtVerifyEmailAddress`, click `#btnEmail`
+  - Response: "Your e-mail request has been received. Please allow 48 hours."
+- Service Request Number is in the URL: `?srNo=XXXXXXXXXXX`
+
+### 15. Deprecation warning
+- `[DEP0169] url.parse() behavior is not standardized` comes from Playwright's Node.js internals
+- Harmless — Playwright uses `url.parse()` in its server; fix is upstream (Playwright issue)
+- Suppress with: `NODE_OPTIONS='--no-deprecation'` env var